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

[AC]

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!