[Python-Dev] query: docstring formatting in python distutils code

[Alexander Belopolsky]

On Wed, Jul 7, 2010 at 2:12 PM, Barry Warsaw <barry at python.org> wrote:
..
> Does it make sense to add (reST-style) epydoc markup for API signatures?
> E.g.
>
> def create_foo(name, parent=None):
>    """Create the named foo.
>
>    The named foo must not already exist, but if optional `parent` is given,
>    it must exist.
>
>    :param name: The name of the new foo.
>    :type name: string
..

-1.  Repeating the function signature in the docstring only adds
clutter and Java-style formal types/exceptions specifications are
rarely appropriate in Python.  I think marking arguments up with * as
in *name*, *parent*, should be enough in most cases.