ufl team mailing list archive

[Anders Logg <logg@xxxxxxxxx>]

On Thu, Aug 21, 2008 at 03:52:35PM +0200, Johan Hake wrote:
> 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

Do we need this? I guess we will need to write a very detailed user
manual anyway (like for UFC) where we document all operators with
mathematical notation. I think if we should spend time on adding
detailed docstrings, the resulting auto-generated manual should be
able to replace much of the written documentation.

-- 
Anders

Attachment: signature.asc
Description: Digital signature