This issue tracker has been migrated to GitHub, and is currently read-only.
For more information, see the GitHub FAQs in the Python's Developer Guide.

Author Banger
Recipients Banger, docs@python, josh.r
Date 2014-05-15.15:13:46
SpamBayes Score -1.0
Marked as misclassified Yes
Message-id <1400166827.18.0.642641732438.issue21508@psf.upfronthosting.co.za>
In-reply-to
Content
I would prefer the function to return "bool".  But what I prefer is irrelevant, what counts is accuracy and clarity.  And to this end, the return type and the comment have to match.

For a int return value, the document should mention a condition relative to an integer value (e.g.: ==0, !=0, ==-1, <0, ==42, etc).

In this particular case, to minimize the changes, success should be defined as !=0 and failure ==0.

Although there is a bigger problem that I mentioned in that the Python C API uses two different return value standards: in most places, ==0 is success, in this case (and some other places) ==0 is a failure.

As for "implementation constraints" I don't see how making the documentation accurate affects that in any way.  If ever the implementation is expanded, the documentation will need to change.  The only alternative is to make the doc vague or simply wrong.
History
Date User Action Args
2014-05-15 15:13:47Bangersetrecipients: + Banger, docs@python, josh.r
2014-05-15 15:13:47Bangersetmessageid: <1400166827.18.0.642641732438.issue21508@psf.upfronthosting.co.za>
2014-05-15 15:13:47Bangerlinkissue21508 messages
2014-05-15 15:13:46Bangercreate