Fix description of buffer_info(), and add a note that there is a better

way...

This closes SF bug #444842.

1 files changed, 15 insertions, 6 deletions

diff --git a/Doc/lib/libarray.tex b/Doc/lib/libarray.tex
index bbbd90b..868770e 100644
--- a/Doc/lib/libarray.tex
+++ b/Doc/lib/libarray.tex
@@ -68,12 +68,21 @@ Append a new item with value \var{x} to the end of the array.
 
 \begin{methoddesc}[array]{buffer_info}{}
 Return a tuple \code{(\var{address}, \var{length})} giving the current
-memory address and the length in bytes of the buffer used to hold
-array's contents.  This is occasionally useful when working with
+memory address and the length in elements of the buffer used to hold
+array's contents.  The size of the memory buffer in bytes can be
+computed as \code{\var{array}.buffer_info()[1] *
+\var{array}.itemsize}.  This is occasionally useful when working with
 low-level (and inherently unsafe) I/O interfaces that require memory
-addresses, such as certain \cfunction{ioctl()} operations.  The returned
-numbers are valid as long as the array exists and no length-changing
-operations are applied to it.
+addresses, such as certain \cfunction{ioctl()} operations.  The
+returned numbers are valid as long as the array exists and no
+length-changing operations are applied to it.
+
+\strong{Note:}  When using array objects from code written in C or
+\Cpp{} (the only way to effectively make use of this information), it
+makes more sense to use the buffer interface supported by array
+objects.  This method is maintained for backward compatibility and
+should be avoided in new code.  The buffer interface is documented in
+the \citetitle[../api/newTypes.html]{Python/C API Reference Manual}.
 \end{methoddesc}
 
 \begin{methoddesc}[array]{byteswap}{}
@@ -174,7 +183,7 @@ string if the \var{typecode} is \code{'c'}, otherwise it is a list of
 numbers.  The string is guaranteed to be able to be converted back to
 an array with the same type and value using reverse quotes
 (\code{``}), so long as the \function{array()} function has been
-imported using \samp{from array import array}.  Examples:
+imported using \code{from array import array}.  Examples:
 
 \begin{verbatim}
 array('l')