[issue8939] Use C type names (PyUnicode etc;) in the C API docs

[Marc-Andre Lemburg]

Marc-Andre Lemburg <mal at egenix.com> added the comment:

STINNER Victor wrote:
> 
> STINNER Victor <victor.stinner at haypocalc.com> added the comment:
> 
> Le mercredi 09 juin 2010 11:06:25, vous avez écrit :
>>>  - replace Python types by C Python types (eg. str => PyUnicodeObject*
>>>  and None => Py_None)
>>
>> I was thinking of e.g. "PyUnicode", not "PyUnicodeObject*".
> 
> I don't know PyUnicode, only "unicode" (Python type) or "PyUnicodeObject*" (C 
> Python type). :ctype:`PyUnicodeObject*` creates a link in the HTML 
> documentation.

The "PyUnicode" style is just an abbreviated version of the longer
"PyUnicodeObject", that we sometimes use, since writing "Pass
a PyUnicodeObject object to this function" looks a bit silly.

I don't have a strong opinion about this, though. The longer
version is fine as well.

>>>  - add quotes to the formats, eg. s => "s"
>>
>> Why do you put the parser codes in double quotes ?
> 
> It's easier to search a format: try to search s or b format in the current 
> documentation, you will see :-)
> 
> I think that it's also more readable and closer to the "real" source code (eg. 
> a call to PyArg_ParseTuple() uses quotes).

It could lead developers into thinking that they have to use
those quotes in their code.

Perhaps you should add a note about this typographic addition
to docs.

>>>  - replace true by 1, and false by 0 (C API of Python doesn't use
>>>  stdbool.h but classic int)
>>
>> That's not necessarily correct: true in C means non-zero. Only
>> false equates to 0. You can however, make that change if the
>> function actually does always return 1.
> 
> There are only 2 possible results: 0 or 1.

I wouldn't count on this. It may be the case now, but it's both
hard to check by reading the code and knowing that only 1 can
be returned doesn't buy a developer much.

In fact, this has
bitten us before with the cmp() function: users starting writing
code like this because we documented the return codes as -1, 0, 1:

a = b + z * cmp(x, y)

Please use "non-zero" instead.

----------

_______________________________________
Python tracker <report at bugs.python.org>
<http://bugs.python.org/issue8939>
_______________________________________