Terry J. Reedy <tjre...@udel.edu> added the comment:
The reason that modules, classes, and functions need a special rule for
assigning the .__doc__ attribute is that one cannot get a reference to the
module, class, or function within the body of its definition. And putting the
docstring at the top of a file or after a header is usually the best place.
For modules, the body is the file, leaving nowhere else to put the docstring.
For classes and functions, the alternative of an assignment elsewhere, after
the object is created, remains.
>>> def f(): pass
>>> f.__doc__ = 'Docstring outside f body'
>>> help(f)
Help on function f in module __main__:
f()
Docstring outside f body
This alternative is used in functools.partial and decorators that wrap
functions with a function and then copy the original docstring to the wrapper.
I think object.doc = 'docstring' is sufficient for other objects and that PEP
224 was wrong to propose otherwise and should have been rejected.
So I think that this issue should propose what Steven said: pydoc/help()
should be simplified to fetch object.__doc__ with normal lookup, instead of
bypassing object if not one of the special types. Stefan Seefeld, can you try
patching pydoc to do this?
If one wants to add docstrings to builtins, a subclass can work.
>>> class Docint(int): pass
>>> i,j = Docint(1), Docint(2)
>>> i+j
3
>>> i.__doc__ = 'one'
We just need help to print i.__doc__ instead of int.__doc__.
----------
nosy: +terry.reedy
stage: -> test needed
versions: +Python 3.8
_______________________________________
Python tracker <rep...@bugs.python.org>
<https://bugs.python.org/issue35449>
_______________________________________
_______________________________________________
Python-bugs-list mailing list
Unsubscribe:
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com
