[Python-checkins] r64113 - python/trunk/Doc/library/ctypes.rst

[thomas.heller]

Author: thomas.heller
Date: Wed Jun 11 09:10:43 2008
New Revision: 64113

Log:
Fix markup.
Document the new 'offset' parameter for the 'ctypes.byref' function.

Modified:
   python/trunk/Doc/library/ctypes.rst

Modified: python/trunk/Doc/library/ctypes.rst
==============================================================================
--- python/trunk/Doc/library/ctypes.rst	(original)
+++ python/trunk/Doc/library/ctypes.rst	Wed Jun 11 09:10:43 2008
@@ -1406,10 +1406,9 @@
 to request and change the ctypes private copy of the windows error
 code.
 
-.. versionchanged:: 2.6
-
-The `use_errno` and `use_last_error` parameters were added in Python
-2.6.
+.. versionadded:: 2.6
+   The ``use_last_error`` and ``use_errno`` optional parameters
+   were added.
 
 .. data:: RTLD_GLOBAL
    :noindex:
@@ -1572,22 +1571,23 @@
       Assign a Python function or another callable to this attribute. The
       callable will be called with three or more arguments:
 
+      .. function:: callable(result, func, arguments)
+         :noindex:
 
-.. function:: callable(result, func, arguments)
-   :noindex:
-
-   ``result`` is what the foreign function returns, as specified by the
-   :attr:`restype` attribute.
-
-   ``func`` is the foreign function object itself, this allows to reuse the same
-   callable object to check or post process the results of several functions.
-
-   ``arguments`` is a tuple containing the parameters originally passed to the
-   function call, this allows to specialize the behavior on the arguments used.
+         ``result`` is what the foreign function returns, as specified
+         by the :attr:`restype` attribute.
 
-   The object that this function returns will be returned from the foreign
-   function call, but it can also check the result value and raise an exception
-   if the foreign function call failed.
+         ``func`` is the foreign function object itself, this allows
+         to reuse the same callable object to check or post process
+         the results of several functions.
+
+         ``arguments`` is a tuple containing the parameters originally
+         passed to the function call, this allows to specialize the
+         behavior on the arguments used.
+
+      The object that this function returns will be returned from the
+      foreign function call, but it can also check the result value
+      and raise an exception if the foreign function call failed.
 
 
 .. exception:: ArgumentError()
@@ -1805,12 +1805,22 @@
    ctypes type or instance.
 
 
-.. function:: byref(obj)
+.. function:: byref(obj[, offset])
 
-   Returns a light-weight pointer to ``obj``, which must be an instance of a ctypes
-   type. The returned object can only be used as a foreign function call parameter.
-   It behaves similar to ``pointer(obj)``, but the construction is a lot faster.
+   Returns a light-weight pointer to ``obj``, which must be an
+   instance of a ctypes type.  ``offset`` defaults to zero, it must be
+   an integer which is added to the internal pointer value.
 
+   ``byref(obj, offset)`` corresponds to this C code::
+
+      (((char *)&obj) + offset)
+
+   The returned object can only be used as a foreign function call
+   parameter.  It behaves similar to ``pointer(obj)``, but the
+   construction is a lot faster.
+
+   .. versionadded:: 2.6
+      The ``offset`` optional argument was added.
 
 .. function:: cast(obj, type)