Re: structured function documentation: preferred markup? (AC)

classic Classic list List threaded Threaded
2 messages Options
Reply | Threaded
Open this post in threaded view
|

Re: 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
_______________________________________________
Doc-SIG maillist  -  [hidden email]
http://mail.python.org/mailman/listinfo/doc-sig
Reply | Threaded
Open this post in threaded view
|

Re: structured function documentation: preferred markup?

AC-20
Thanks for your response!

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

That'd be great, as it would fix my biggest gripe with Epytext.
Will that also allow for multiple types (e.g. "@param bar (str, list): ... ")?

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

I'll simply start using that syntax now, and wait for the official announcement.
(Is there an RSS feed I can subscribe to? Couldn't find any on
http://epydoc.sourceforge.net.)

> Be sure to define the __docformat__ module-level variable

Thanks for the hint - will do!

> 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

That's exactly what I'm after.

Any pointers on the issues mentioned in my previous addendum (optional arguments
and valid argument values) - should those be put into the description part?

Thanks again!

_______________________________________________
Doc-SIG maillist  -  [hidden email]
http://mail.python.org/mailman/listinfo/doc-sig