[Python-Dev] query: docstring formatting in python distutils code (original) (raw)

Alexander Belopolsky alexander.belopolsky at gmail.com
Wed Jul 7 20:46:49 CEST 2010

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 createfoo(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.

More information about the Python-Dev mailing list