classification
Title: Incorrect documentation of the PyObject_HEAD macro
Type: behavior Stage: resolved
Components: Documentation Versions: Python 3.5, Python 3.1, Python 3.2, Python 3.3, Python 3.4
process
Status: closed Resolution: fixed
Dependencies: Superseder:
Assigned To: gregory.p.smith Nosy List: akuchling, docs@python, gregory.p.smith, python-dev, trovao, wiggin15, ysj.ray
Priority: normal Keywords: patch

Created on 2010-06-16 19:58 by trovao, last changed 2016-04-19 13:10 by berker.peksag. This issue is now closed.

Files
File name Uploaded Description Edit
issue9014.diff wiggin15, 2015-04-14 16:07
issue.txt akuchling, 2015-04-14 18:12 Added more markup
Messages (9)
msg107953 - (view) Author: Renato Cunha (trovao) Date: 2010-06-16 19:58
PyObject_HEAD's documentation in py3k (http://docs.python.org/dev/py3k/c-api/structures.html#PyObject_HEAD) uses the same content used in the python 2.x's docs which is wrong, as there were some API changes.

PyObject_HEAD is actually defined as

#define PyObject_HEAD PyObject ob_base;

with PyObject defined as

typedef struct _object {
    _PyObject_HEAD_EXTRA
    Py_ssize_t ob_refcnt;
    struct _typeobject *ob_type;
} PyObject;

(The PyTRACE_REFS discussion is still valid, though.)

Additionally, it'd be nice to mention that the Py_REFCNT(ob) and Py_TYPE(ob) macros should be used to access the PyObject members.
msg122333 - (view) Author: ysj.ray (ysj.ray) Date: 2010-11-25 06:07
Additionally, I prefer move the discussion of Py_TRACE_REFS under the documentation of PyObject: http://docs.python.org/dev/py3k/c-api/structures.html?highlight=pyobject_head#PyObject, since they'are connected directly. The doc of PyObject_HEAD should only saying like "expands to a PyObject variable".
msg240926 - (view) Author: Arnon Yaari (wiggin15) * Date: 2015-04-14 16:07
PEP 3123 is the one that describes this change. I'm submitting a file with the proposed changes to the docs.
msg240970 - (view) Author: A.M. Kuchling (akuchling) * (Python committer) Date: 2015-04-14 18:12
Did you intend to remove the discussion of Py_TRACE_REFS completely?  (I've reworked your patch a little bit, adding some markup such as :c:macro:`Py_REFCNT`.)
msg240971 - (view) Author: Roundup Robot (python-dev) Date: 2015-04-14 18:13
New changeset 760c5cfacbaa by Gregory P. Smith in branch '3.4':
issue9014: Properly document PyObject_HEAD and friends post-PEP-3123.
https://hg.python.org/cpython/rev/760c5cfacbaa

New changeset 7dc8f0075d60 by Gregory P. Smith in branch 'default':
issue9014: Properly document PyObject_HEAD and friends post-PEP-3123.
https://hg.python.org/cpython/rev/7dc8f0075d60
msg240972 - (view) Author: Gregory P. Smith (gregory.p.smith) * (Python committer) Date: 2015-04-14 18:14
i used wiggin15's patch to start with.  I'm now looking at akuchling's patch and will incorporate any additional things it adds (I missed that earlier).
msg240973 - (view) Author: A.M. Kuchling (akuchling) * (Python committer) Date: 2015-04-14 18:17
The markup is not a huge deal, I think.  I also did some bits of rewording that can probably be ignored.  The TRACE_REFS question is the only important one, I think.
msg240976 - (view) Author: Roundup Robot (python-dev) Date: 2015-04-14 18:21
New changeset 752ea0acc37e by Gregory P. Smith in branch '3.4':
issue9014: Include more formatting on :c:type:`PyObject` etc.
https://hg.python.org/cpython/rev/752ea0acc37e

New changeset 78a2d1169be1 by Gregory P. Smith in branch 'default':
issue9014: Include more formatting on :c:type:`PyObject` etc.
https://hg.python.org/cpython/rev/78a2d1169be1
msg240980 - (view) Author: Gregory P. Smith (gregory.p.smith) * (Python committer) Date: 2015-04-14 18:24
We no longer describe the contents of PyObject in the docs so mentioning Py_TRACE_REFS does not seem worth it as that just changes Py_HEAD_EXTRA which adds the doubly linked list to PyObject (today).

Py_TRACE_REFS isn't useful for anyone to know about IMNSHO as it's a compile time define that normally comes from choosing to do a pydebug build.  (I believe we have or have at least had bugs in our code where Py_TRACE_REFS won't work if Py_DEBUG is not also defined as we never test in such a mixed non-DEBUG but with TRACE_REFS configuration)
History
Date User Action Args
2016-04-19 13:10:40berker.peksagsetstage: commit review -> resolved
2015-04-14 18:24:53gregory.p.smithsetstatus: open -> closed
versions: + Python 3.4, Python 3.5
messages: + msg240980

resolution: fixed
stage: commit review
2015-04-14 18:21:40python-devsetmessages: + msg240976
2015-04-14 18:17:00akuchlingsetmessages: + msg240973
2015-04-14 18:14:46gregory.p.smithsetassignee: docs@python -> gregory.p.smith

messages: + msg240972
nosy: + gregory.p.smith
2015-04-14 18:13:34python-devsetnosy: + python-dev
messages: + msg240971
2015-04-14 18:12:35akuchlingsetfiles: + issue.txt
nosy: + akuchling
messages: + msg240970

2015-04-14 16:07:09wiggin15setfiles: + issue9014.diff

nosy: + wiggin15
messages: + msg240926

keywords: + patch
2010-11-25 06:07:33ysj.raysetnosy: + ysj.ray
messages: + msg122333
2010-06-16 19:58:48trovaocreate