> 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
_______________________________________________
Doc-SIG maillist - Doc-SIG@python.org
http://mail.python.org/mailman/listinfo/doc-sig
