ufl team mailing list archive

[Johan Hake <hake@xxxxxxxxx>]

On Thursday 21 August 2008 15:07:49 Martin Sandve Alnæs wrote:
> Should we use epydoc in UFL? Then we can generate a nice hyperlinked
> reference documentation.
>
> Example:
>
> def inverse(A):
>     """The inverse of A.
>
>     @type A: UFLObject
>     @param A: Nonsingular rank 2 tensor (matrix).
>     @rtype: UFLObject
>     @return: The matrix that is the inverse of A.
>     """
>     ...

I have choosen epydoc/epytext for the docstrings of my code. 

I looked a bit into reStructruredText (RST), as it is an established standard. 
In a hypothetical senario we could risk that the development of epydoc ends, 
but that not likely for RST. It is also a PEP* about including RST as a 
standard for the docstrings for the python library. Although there are some 
good arguments for RST, I felt that it was too cumbersome to write docstrings 
using it.

[*] <http://www.python.org/dev/peps/pep-0287>

Johan