ufl team mailing list archive

["Martin Sandve Alnæs" <martinal@xxxxxxxxx>]

2008/8/21 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

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