[Doc-SIG] structured function documentation: preferred markup? (AC)

[Edward Loper]

> In order to simplify maintenance, I'm committed to providing structured
> documentation for all of my code. [...]
>
> However, that seems excessively verbose due to the separate line for type
> information.

Hi, I'm the author of epydoc.

I just wanted to mention that the next item on my to-do list for
epydoc is to add support for the following syntax:

@param bar (str): description of bar...

The analogous syntax would also be supported for restructuredtext:

:param bar (str): description of bar...

Note that you can already do the following in epydoc when using
restructuredtext:

:parameters:
   bar : str
       description of bar...
   baz: int
       description of baz...

My guess is that it'll be a couple weeks before I get time to
implement this, if you can wait that long.

As for whether there's a standard markup for docstrings -- not really.
 Be sure to define the __docformat__ module-level variable, so that
any program like epydoc can tell what markup language you're using.
E.g.:

__docformat__ = 'restructuredtext'

or

__docformat__ = 'epytext'

My personal recommendation would be to use epytext if you're happy
with a very lightweight markup language that doesn't support many
advanced features (tables, images, etc); or restructuredtext
otherwise.  Both epytext and restructuredtext are quite
human-readable, even for people who are not familiar with the markup
languages, which I think is important.

-Edward