fenics team mailing list archive

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

On 27/08/10 12:09, Anders Logg wrote:
> On Fri, Aug 27, 2010 at 12:12:59PM +0200, Kristian Ølgaard wrote:
>> On 27 August 2010 12:00, Garth N. Wells <gnw20@xxxxxxxxx> wrote:
>>>
>>>
>>> On 27/08/10 10:51, Kristian Ølgaard wrote:
>>>> On 27 August 2010 11:31, Garth N. Wells <gnw20@xxxxxxxxx> wrote:
>>>>>
>>>>>>>>>> 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.
>>>>
>>>> As I wrote above, a test script is in place to pick up
>>>> missing/obsolete docs, very little extra work is needed to also test
>>>> if the short docstring in the source  code is correct. Then we run the
>>>> tests as part of building the documentation.
>>>>
>>>
>>> I just can't see myself hopping back and forth between the code and the
>>> documentation when implementing and testing something new.
>>
>> I don't see why that would be necessary, the documentation can be
>> updated and built later once the feature is in place and tested.
>> But the feature can't be 'official' until it has been documented, it
>> will require more self-discipline from the developers, which I don't
>> think is necessarily a bad idea.
>>
>>>> I admit that the Doxygen output is much more detailed and the type
>>>> information/links in argument lists is better compared to what is in
>>>> Sphinx now, but that might change in the future (in Sphinx). On the
>>>> downside, I personally find the Doxygen documentation overwhelming and
>>>> I never use it for just that reason.
>>>>
>>>
>>> Doxygen is an (imperfect) ready made solution for the programmers
>>> reference - so one of my points is that we can forget about the C++
>>> programmers reference for now and get on with the more importance task
>>> of documenting demos. We can return to the C++ programmers reference
>>> later (which, as you say, may improve in Sphinx in the future).
>>
>> I'm fine with using Doxygen and simply put a link to the index page, I
>> just think it is worthwhile to carefully discuss the pros and cons.
>>
>> The Python interface still has to be documented manually since there
>> is no way to extract docstrings from the source code since the
>> intention is to add docstrings to the module.
>>
>>> We can some some very limited work to improve the doxygen output which
>>> will make it easier to navigate.
>>
>> I just don't see how this can be integrated easily with the output from Doxygen.
>> We don't want to manipulate the output files since they will be
>> re-generated whenever we build the docs. It is possible though to link
>> to the html pages of classes/functions, but it won't be naturally
>> supported like it would be if everything is in Sphinx.
>>
>> Kristian
> 
> I think that the simple script we have now does a fairly good job at
> extracting the documentation. I like having it as part of the
> reST-based documentation (so it looks like it's part of the
> documentation), rather than as a separate set of pages generated by
> Doxygen. But I wouldn't mind having Doxygen-generated pages in
> addition.
> 

The doc generated by the script lacks links, which is a big drawback.

Garth

> I agree with Garth that it will be difficult to jump between two
> different repositories to make updates every time we change the name
> of an argument to a function, or add a new function.
> 
> Maybe we could try to put the documentation Kristian has written in
> reST for the Mesh class into Mesh.h and see how that works out.
> 
> I don't think it will be much of a problem to have it there,
> especially if we employ some folding mode in our editors.
> 
> --
> Anders