fenics team mailing list archive

[Anders Logg <logg@xxxxxxxxx>]

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.

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