fenics team mailing list archive

["Garth N. Wells" <gnw20@xxxxxxxxx>]

>>>>> The stuff that you have written for the Mesh class could easily go in
>>>>> to Mesh.h without causing too much clutter (reST looks nice), and I
>>>>> imagine it would be easy to add a folding mode to Emacs and other
>>>>> editors that will hide all lines starting with /// except for the
>>>>> first line.
>>>>>
>>>>> The simple script I wrote seems to work pretty well to extract the
>>>>> documentation. If it breaks somewhere, we could either improve the
>>>>> script or learn to write the code so the script does not break.
>>>>>
>>>>> The point here is that now the generated .rst files are in sync with
>>>>> the code, but in a day or two someone will edit one of the .h files in
>>>>> DOLFIN and the documentation and code will start to diverge.
> 
> On second thought, what do you mean by diverge?
> I have test scripts in place the checks if a function in *.h is
> documented in *.rst, and if a function in *.rst is still present in
> *.h.
> 
> If you mean the docstrings might change, we can perform the additional
> check where we test if the one liner docstring in *.h is present in
> the documentation in *.rst, then there can be no divergence and we can
> have short comments in the DOLFIN source code.
> 
>>> Yes, but this problem is already there for the Python interface and it
>>> won't go away.
>>> I guess the key thing to this is that a new feature or a change in
>>> DOLFIN source code is not complete until the documentation has been
>>> updated.
>>>
>>
>> To save ourselves work for now, we could just let doxygen create the C++
>> programmers reference and provide a link to it. It doesn't seem very
>> sensible that we write our own parser to document the C++ code. With
>> doxygen, we also get class diagrams. We can then scan the doxygen
>> documentation for each class and improve it iteratively.
> 
> Do you mean improve the Doxygen output, or the source  code (*.h
> files)? If we improve the output we can get diverging docs and code.
> 

I mean improve the strings following '///' in the .h files. In quite
some cases, just a few extra words would make a big difference.

I'm coming around to putting all programming reference doc in the code.
I don't like lots of markup, but I don't see any other robust and easily
maintainable solution.

Perhaps we should settle on well crafted, handwritten docs for the demos
(which is the most important), and all programming reference docs coming
automatically from the source code. When scanning auto generated docs,
it easy to pick up quickly where more detail needs to be added, and we
can open open up the source and add it.

Garth

> I had a look at the Breathe generated docs from Doxygen, it doesn't
> look that great and we won't have all the links from the index page to
> the classes.
> 
> Kristian
> 
>> Garth
>>
>>> Kristian
>>>
>>>>> --
>>>>> Anders
>>>>>
>>>>> _______________________________________________
>>>>> Mailing list: https://launchpad.net/~fenics
>>>>> Post to     : fenics@xxxxxxxxxxxxxxxxxxx
>>>>> Unsubscribe : https://launchpad.net/~fenics
>>>>> More help   : https://help.launchpad.net/ListHelp
>>>>
>>