[Python-ideas] docstring in decorator?

[Antoine Pitrou]

On Wed, 1 May 2013 19:06:36 +1000
Nick Coghlan <ncoghlan at gmail.com> 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).

Or perhaps pydoc should be smarter and walk the __mro__ until it finds
a __doc__.

Regards

Antoine.