structured function documentation: preferred markup?

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

structured function documentation: preferred markup?

AC-20
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  -  [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
> I'm currently using Epytext [...]
> However, that seems excessively verbose

Also, I'm not sure how to indicate optional arguments, as well as valid values
for certain arguments (e.g. action=["GET"|"PUT"|"POST"|"DELETE"]).

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