Raymond Hettinger added the comment:

Most of the proposed update look reasonable updates and would improve the 
documentation.  

That said, please take care to not accidentally document and unintentionally 
guarantee implementation details rather than language requirements (leaving 
freedom for future changes to implementation and freedom for IronPython, PyPy, 
and Jython to use their best possible implementations).

Sizeof is a CPython specific implementation detail.

I also have reservations about class.__instancecheck__() and 
class.__subclasscheck__() which are more appropriately described in a section 
on abstract base classes than for the otherwise simple and clear docs for 
isinstance() and issubclass().

The sort() method does guarantee use of __lt__ but other tools that make 
comparisons make or may not follow that lead (i.e. heapq used to use __le__ and 
collections.abc.Set uses both __le__ and __ge__).  Accordingly, there is a PEP 
8 recommendation to use @functools.total_ordering rather than supplying just a 
single rich comparison method).

One other thought is to keep the additions as brief as possible to not distract 
from the main message of each section; keeping the docs primarily focused on 
what a function does rather than how it does it, and remembering that making 
the docs more lengthly impairs their utility for everyday use.  Our docs are 
already much more chatty than equivalents in Java and Go (it used to take five 
minutes to read the docs for the builtin functions and now it takes an hour). 

There is also a matter of keeping the docs approachable for normal people.  For 
most folks, saying that hex(num) returns a string with the number in 
hexadecimal would suffice.  Adding notes about the exact case of the letters, 
handling of negatives, use of __int__ and __index__, and comparisons with 
string formatting, and multiple examples beats a dead horse and makes a simple 
tool seem more complex.

Though I think this so go forward, I'm marking it with "low" priority because 
we don't have any evidence that users have found the current docs to be 
inadequate -- they have served well over Python's long history.   Cases we've 
gone into details like __format__ or __next__ were there because they we 
essential to the tool; in contrast, it is unlikely that a user would ever need 
to know the sys.getsizeof() delegated its work to __sizeof__.

----------
nosy: +rhettinger
priority: normal -> low

_______________________________________
Python tracker <rep...@bugs.python.org>
<http://bugs.python.org/issue10289>
_______________________________________
_______________________________________________
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

Reply via email to