Marc-Andre Lemburg <m...@egenix.com> added the comment: STINNER Victor wrote: > > STINNER Victor <victor.stin...@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 <rep...@bugs.python.org> <http://bugs.python.org/issue8939> _______________________________________ _______________________________________________ Python-bugs-list mailing list Unsubscribe: http://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com
