[Python-checkins] bpo-29916: Include PyGetSetDef in C API extension documentation. (#831) (#3607)

[Serhiy Storchaka]

https://github.com/python/cpython/commit/51ea80697b023595cdd79c7696589a04cc581693
commit: 51ea80697b023595cdd79c7696589a04cc581693
branch: 3.6
author: Michael Seifert <michaelseifert04 at yahoo.de>
committer: Serhiy Storchaka <storchaka at gmail.com>
date: 2017-09-16T14:29:33+03:00
summary:

bpo-29916: Include PyGetSetDef in C API extension documentation. (#831) (#3607)

(cherry picked from commit da67e0d644bd3185efdaa4d15cc2ac0828ca83f9)

files:
M Doc/c-api/structures.rst
M Doc/c-api/typeobj.rst

diff --git a/Doc/c-api/structures.rst b/Doc/c-api/structures.rst
index c080f317bee..675f6f26921 100644
--- a/Doc/c-api/structures.rst
+++ b/Doc/c-api/structures.rst
@@ -294,3 +294,43 @@ definition with the same method name.
    read-only access.  Using :c:macro:`T_STRING` for :attr:`type` implies
    :c:macro:`READONLY`.  Only :c:macro:`T_OBJECT` and :c:macro:`T_OBJECT_EX`
    members can be deleted.  (They are set to *NULL*).
+
+
+.. c:type:: PyGetSetDef
+
+   Structure to define property-like access for a type. See also description of
+   the :c:member:`PyTypeObject.tp_getset` slot.
+
+   +-------------+------------------+-----------------------------------+
+   | Field       | C Type           | Meaning                           |
+   +=============+==================+===================================+
+   | name        | char \*          | attribute name                    |
+   +-------------+------------------+-----------------------------------+
+   | get         | getter           | C Function to get the attribute   |
+   +-------------+------------------+-----------------------------------+
+   | set         | setter           | optional C function to set or     |
+   |             |                  | delete the attribute, if omitted  |
+   |             |                  | the attribute is readonly         |
+   +-------------+------------------+-----------------------------------+
+   | doc         | char \*          | optional docstring                |
+   +-------------+------------------+-----------------------------------+
+   | closure     | void \*          | optional function pointer,        |
+   |             |                  | providing additional data for     |
+   |             |                  | getter and setter                 |
+   +-------------+------------------+-----------------------------------+
+
+   The ``get`` function takes one :c:type:`PyObject\*` parameter (the
+   instance) and a function pointer (the associated ``closure``)::
+
+      typedef PyObject *(*getter)(PyObject *, void *);
+
+   It should return a new reference on success or *NULL* with a set exception
+   on failure.
+
+   ``set`` functions take two :c:type:`PyObject\*` parameters (the instance and
+   the value to be set) and a function pointer (the associated ``closure``)::
+
+      typedef int (*setter)(PyObject *, PyObject *, void *);
+
+   In case the attribute should be deleted the second parameter is *NULL*.
+   Should return ``0`` on success or ``-1`` with a set exception on failure.
diff --git a/Doc/c-api/typeobj.rst b/Doc/c-api/typeobj.rst
index ac6fd0b53fc..0b4577f5b95 100644
--- a/Doc/c-api/typeobj.rst
+++ b/Doc/c-api/typeobj.rst
@@ -719,21 +719,6 @@ type objects) *must* have the :attr:`ob_size` field.
    This field is not inherited by subtypes (computed attributes are inherited
    through a different mechanism).
 
-   .. XXX belongs elsewhere
-
-   Docs for PyGetSetDef::
-
-      typedef PyObject *(*getter)(PyObject *, void *);
-      typedef int (*setter)(PyObject *, PyObject *, void *);
-
-      typedef struct PyGetSetDef {
-          char *name;    /* attribute name */
-          getter get;    /* C function to get the attribute */
-          setter set;    /* C function to set or delete the attribute */
-          char *doc;     /* optional doc string */
-          void *closure; /* optional additional data for getter and setter */
-      } PyGetSetDef;
-
 
 .. c:member:: PyTypeObject* PyTypeObject.tp_base