fenics team mailing list archive

[Kristian Ølgaard <k.b.oelgaard@xxxxxxxxx>]

On 26 August 2010 18:22, Anders Logg <logg@xxxxxxxxx> wrote:
> I've thought some more on how to organize/synchronize the FEniCS
> documentation (in fenics-doc) with the documentation we have in the
> code.
>
> I think it is important that
>
> (1) the strings we have in the code are the same as those that appear
> on in the HTML documentation (which we write in Sphinx).
>
> (2) the strings we have in the code are short (so they don't clutter
> up the code)

I disagree. The whole idea of the documentation effort was to document
in one place
(using carefully handwritten and elaborate explanations including
examples and links to demos etc.) and code in another.
The comments in the code should be very short and precise such that
together with the class/function definition and type info the
developer can complete the task without looking elsewhere. These kind
of comments, I expect, will look weird when put next to an elaborate
explanation on how the class/function works including all the bells
and whistles.

> If we look at these two, it seems that (1) implies that we should
> write the documentation as part of the code and then extract it using
> some tool.
>
> But (2) prevents that since we don't want to constrain the
> documentation for all functions to be very short.
>
> How about the following solution.
>
> * Write short docstrings in the code
>
> * Auto-generate all the .rst input files for the Programmer's
>  Reference using a simple Python script that looks for '///'
>
> * The script looks at the code to generate the signature of the
>  function and the text that comes immediately after.

This might be possible for a simple
'change-order-of-comment-and-function' script where you manipulate the
output manually afterwards, but if you want to run this more than once
you will have to pick up nested class/struct definitions templates and
all kinds of crap.
I tried to write a parser like this to check if all classes and
functions were documented, but gave up and let Doxygen do the dirty
work. (But do we want to do this just to generate 20 characters of
docstring automatically?)

>  But it also looks in a hand-written .rst file that contains any
>  additional stuff we want to put below.
>
> So for the code example in the style manual, the things that get
> picked up from the code are
>
>  // Return the cell which is closest to the given point
>  uint closest_cell(const Point & point) const
>
> which gets converted to
>
> .. cpp:function:: uint closest_cell(const Point & point) const
>
>    Return the cell which is closest to the given point
>
> The script also looks in a file for "closest_cell" below which we have
> written all the *Arguments* stuff that will be thrown in below.
>
> Will that work?

Yes, but the work flow is getting complex, and you'll need to know
what you get from the source code so you don't repeat yourself.
It is much easier to have the documentation in one place.

> Another solution would be to just write everything as part of the
> code, and just add some settings to our editors that will fold the
> extra stuff away so we don't need to see it. Maybe that is the most
> robust solution?

The general consensus the last time this issue came up was not to
clutter the code with documentation markup.

Kristian

> --
> Anders
>
> _______________________________________________
> Mailing list: https://launchpad.net/~fenics
> Post to     : fenics@xxxxxxxxxxxxxxxxxxx
> Unsubscribe : https://launchpad.net/~fenics
> More help   : https://help.launchpad.net/ListHelp
>