Hello,
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
"""
pass
However, that seems excessively verbose due to the separate line for type
information.
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
_______________________________________________
Doc-SIG maillist - Doc-SIG@python.org
http://mail.python.org/mailman/listinfo/doc-sig
