[Python-ideas] docstring in decorator?

[Nick Coghlan]

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).

Cheers,
Nick.

--
Nick Coghlan   |   ncoghlan at gmail.com   |   Brisbane, Australia