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

AC gmane.0vd at gishpuppy.com
Wed Aug 27 21:27:21 CEST 2008


First of all, I hope this is the right group to ask this in.
My apologies if that's not the case.

In order to simplify maintenance, I'm committed to providing structured
documentation for all of my code.
However, I'm not sure which markup language is preferred in the Python world -
or whether there is any consensus at all.

I'm currently using Epytext:
    def foo(bar):
        lorem ipsum dolor sit amet

        @param bar: consectetur adipisicing elit
        @type  bar: str
        @return: None
        @rtype : None

However, that seems excessively verbose due to the separate line for type
I know there are alternatives (namely, Javadoc and reStructuredText) - but if
they're not widely used, there's not much sense in me using those.*

Any guidance would be greatly appreciated!

* I know that Epydoc, for example, can generate documentation from various
markup languages - however, my main concerns is the documentation directly
within the source code

More information about the Doc-SIG mailing list