Author terry.reedy
Recipients stefan, steven.daprano, terry.reedy, xtreak
Date 2018-12-14.20:42:50
SpamBayes Score -1.0
Marked as misclassified Yes
Message-id <1544820170.46.0.788709270274.issue35449@psf.upfronthosting.co.za>
In-reply-to
Content
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__.
History
Date User Action Args
2018-12-14 20:42:50terry.reedysetrecipients: + terry.reedy, stefan, steven.daprano, xtreak
2018-12-14 20:42:50terry.reedysetmessageid: <1544820170.46.0.788709270274.issue35449@psf.upfronthosting.co.za>
2018-12-14 20:42:50terry.reedylinkissue35449 messages
2018-12-14 20:42:50terry.reedycreate