On Fri, Aug 27, 2010 at 12:12:59PM +0200, Kristian Ølgaard wrote: > On 27 August 2010 12:00, Garth N. Wells <[email protected]> wrote: > > > > > > On 27/08/10 10:51, Kristian Ølgaard wrote: > >> On 27 August 2010 11:31, Garth N. Wells <[email protected]> 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 _______________________________________________ Mailing list: https://launchpad.net/~fenics Post to : [email protected] Unsubscribe : https://launchpad.net/~fenics More help : https://help.launchpad.net/ListHelp
