Subject: [UFL-dev] Docstrings

From: "Martin Sandve Alnæs" <[email-masked]>
Date: Thu, 21 Aug 2008 15:07:49 +0200

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.
    """
    ...

-- 
Martin

---

From: Johan Hake <[email-masked]>
Date: Thu, 21 Aug 2008 15:52:35 +0200

>     @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

---

From: Anders Logg <[email-masked]>
Date: Thu, 21 Aug 2008 21:35:56 +0200

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

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

---

From: "Martin Sandve Alnæs" <[email-masked]>
Date: Fri, 22 Aug 2008 09:02:18 +0200

> able to replace much of the written documentation.

We don't need to provide detailed docstrings with @param and @type etc.
for most functions, a good manual should be enough. But every function
should have at least a short docstring, and for _some_ functions we may
want to add more details. So we won't use special tags that many places
anyway.

--
Martin