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 <[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. >
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 _______________________________________________ Mailing list: https://launchpad.net/~fenics Post to : [email protected] Unsubscribe : https://launchpad.net/~fenics More help : https://help.launchpad.net/ListHelp
