[docs] Update documented signatures of tp_get/setattr (issue 28771)

[vadmium+py at gmail.com]

Reviewers: storchaka,


https://bugs.python.org/review/28771/diff/19257/Doc/c-api/typeobj.rst
File Doc/c-api/typeobj.rst (right):

https://bugs.python.org/review/28771/diff/19257/Doc/c-api/typeobj.rst#newcode204
Doc/c-api/typeobj.rst:204: PyObject * tp_getattr(PyObject *o, char
*attr_name);
On 2016/11/22 13:13:41, storchaka wrote:
> Shouldn't we use the ".. code-block:: c" directive?

I don’t think it is needed. At the top of the file there is already “..
highlightlang:: c”, and this already comes up highlighted for me. I
copied the markup from
<https://docs.python.org/3.7/c-api/typeobj.html#c.PyTypeObject.tp_descr_get>
further down the page.

> Please document explicitly that attr_name point't to read-only string,
its
> content shouldn't be modified.

Do you mean the function that implements tp_getattr should not modify
the string? I guess I can add that if you want, though it seems to be
going into more detail than normal. It seems reasonable to leave it out,
along with other details like the string is null-terminated and its
lifetime is the duration of the function call.

https://bugs.python.org/review/28771/diff/19257/Doc/c-api/typeobj.rst#newcode219
Doc/c-api/typeobj.rst:219: PyObject * tp_setattr(PyObject *o, char
*attr_name, PyObject *v);
On 2016/11/22 13:13:41, storchaka wrote:
> Please document explicitly that "setting *v* to *NULL* to delete an
attribute
> must be supported".

Okay.



Please review this at https://bugs.python.org/review/28771/

Affected files:
  Doc/c-api/typeobj.rst


# HG changeset patch
# Parent  c51045920410a2d63c7e4188a1865ea5c04fc93a
Issue #28769: Update documented signatures of PyTypeObject methods

diff -r c51045920410 Doc/c-api/typeobj.rst
--- a/Doc/c-api/typeobj.rst	Tue Nov 22 19:43:11 2016 +0900
+++ b/Doc/c-api/typeobj.rst	Tue Nov 22 11:44:00 2016 +0000
@@ -199,8 +199,9 @@
 
    This field is deprecated.  When it is defined, it should point to a function
    that acts the same as the :c:member:`~PyTypeObject.tp_getattro` function, but taking a C string
-   instead of a Python string object to give the attribute name.  The signature is
-   the same as for :c:func:`PyObject_GetAttrString`.
+   instead of a Python string object to give the attribute name.  The signature is ::
+
+      PyObject * tp_getattr(PyObject *o, char *attr_name);
 
    This field is inherited by subtypes together with :c:member:`~PyTypeObject.tp_getattro`: a subtype
    inherits both :c:member:`~PyTypeObject.tp_getattr` and :c:member:`~PyTypeObject.tp_getattro` from its base type when
@@ -213,9 +214,9 @@
 
    This field is deprecated.  When it is defined, it should point to a function
    that acts the same as the :c:member:`~PyTypeObject.tp_setattro` function, but taking a C string
-   instead of a Python string object to give the attribute name.  The signature is
-   the same as for :c:func:`PyObject_SetAttrString`, but setting
-   *v* to *NULL* to delete an attribute must be supported.
+   instead of a Python string object to give the attribute name.  The signature is ::
+
+      PyObject * tp_setattr(PyObject *o, char *attr_name, PyObject *v);
 
    This field is inherited by subtypes together with :c:member:`~PyTypeObject.tp_setattro`: a subtype
    inherits both :c:member:`~PyTypeObject.tp_setattr` and :c:member:`~PyTypeObject.tp_setattro` from its base type when