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
