[Doc-SIG] Docstring Standards

[Mahrt, Dallas]

Background: I am in the process of defining some internal programming
standards for my company. One aspect we are keenly interested in is defining
the docstring syntax such that we can facilitate documentation generation
(similar to Doxygen or JavaDoc which we use currently) I have read about the
docutils project and feel it is probably the best fit (in the long term) for
our needs, however I have a question.

1) Method signatures. 
In Doxygen and JavaDoc, there is an explicit ''@param'' syntax for defining
the documentation related to a parameter. There are similar constructs for
''@exception'' and ''@return''. The only thing similar I have found in
docutils documentations is the use of explicit roles. Ex.

    def foo(bar):
        """This is foo.

        :parameter"`foo` - This is a foo
        """

Is this the *standard* way of documenting parameters? If not is there a
standard? If so is there a similar concept for raised exceptions and return
values? 

The only thing I've noticed in practice are English descriptions with
literal references. Ex.

    def foo(bar):
        """This is foo.

        Passes `foo` which is a foo.
        """

This seems to be more difficult to extract the description from the
identifier for a more tabular representation (like JavaDoc)

---
Dallas S. Mahrt              dallasm@aiinet.com
Software Engineer            Applied Innovation Inc.