[Python-ideas] docstring in decorator?

[Masklinn]

On 2013-05-01, at 11:06 , Nick Coghlan wrote:

> On Wed, May 1, 2013 at 6:11 PM, Peter Norvig <peter at norvig.com> wrote:
>> Docstring in decorator:
>> 
>>    @doc("""Compute the square of the number x.
>>    For example, square(3) == (3 * 3) == 9.""")
>>    def square(x): return x * x
>> Disadvantage:
>> 
>> * If it ain't broke, don't fix it.
> 
> * The signature becomes harder to read
> 
> That said, I think the main advantage of using the decorator is the
> ability to more easily set the docstring *programmatically* (which you
> did list as a benefit). I've been thinking we may want a
> "@inheritdocs" class decorator, too (which would replace any "__doc__
> is None" entries in methods with the docs from the parent methods).

Could make sense, considering there's already functools.update_wrapper
which does that, it could be used for more decorators.

As an aside, isn't help() supposed to use __doc__? Because I tried
using update_wrapper() on a partial() to give it the docstring of
the wrapped partially applied function, but help() still yields
partial's documentation and ignores the (correctly set, I checked)
__doc__. Which makes partial() much less interesting across package
boundaries since library users can be expected to lookup the "online"
documentation of exposed or returned objects.

help()'s doc does not mention how it generates help pages, pydoc's
doc page doesn't either.