Doxygen?

[coppolachan]

What is the point of view of the developers on starting to write the doxygen annotations before the code becomes too big?
Any other suggestion about the documentation?

[paboyle]

Personally, I don't like Doxy tagging; it's the sort of thing that doubles the edit work when changing
something and repeating the parameters of a function in comments is just torture for me.

The result is that the tags are always less well maintained than the code, so out of date or missing
and I prefer to not doxy tag and simply aim for maximum clarity and readability in the code.

I think that an API definition document is smart, something in latex that is written in the style of the
present QDP++ manual makes sense. Defining how the code is supposed to behave in a way that
is not simply saying "it is the current implementation" is wise. One of the things on the "TODO" list as far as I recall. Certainly something I have promised to do for RBC.

[mspraggs]

I'm strongly in favour of this. The QDP++ manual is an invaluable introduction to the overall structure and design of the package, which is something that is impossible to gain by simply reading the code, and hence essential to newcomers.

[coppolachan]

A good manual is really important for the final user that want to start learning the code. No doubt, and we should definitely write.
About doxygen: I found it really useful to navigate a big code, because the definition and use of classes, variables, methods, can be scattered around. Doxygen provides the tree view, the automatic links and several other things useful to quickly jump among files/definitions. Chroma without doxygen is a nightmare to learn.

[coppolachan]

I rebump this since documentation is becoming necessary.
I remain of the view that an automatic, surfable, documentation of the code is necessary together with a thorough description a la QDP++ (which has the same issue of being up-to-date since depends on us anyway). Especially since we have so many templated classes that really needs navigation in the code to understand the full structure.

[aportelli]

Just wondering about this issue considering an soonish 0.6 release. Is Doxygen generation working, is there anything to do here?

[paboyle]

we have to make sure doxygen is optional, since not every system will have doxygen
so, adding a configure flag --enable-doxygen to build the html is the best option, with a default of "off".

[coppolachan]

agree on it being optional with a flag.

Doxygen generation has not been tested but it should work as most of the code is just c++.
At least gives the surfable, uncommented, html.

[aportelli]

I can take care of that.

[aportelli]

Hi Guido,
I managed to create something a bit nicer with Doxygen. You can now use --enable-doxygen-doc with configure to enable the HTML doc. Then make doxygen-doc build the doc. I have put that in feature/doxygen. Could you see if it is ok for you and merge it back to develop when everything is ok?

[coppolachan]

Ok, let me check. Not immediately as I'm concentrating on the hirep stuff, but in time for the 0.6 release.

[aportelli]

Hi Guido could you please check that the new build options for Doxygen are good for you in feature/doxygen so that I can merge it back to develop?

[coppolachan]

Few things that are not clear (compiling with clang, I have dot and doxygen in my path)

How to compile to get just the html? --enable-doxygen does not seem to work and the configure --help does not say much.

I tried --enable-doxygen-dot and --enable-doxygen-pdf too and in both cases it complains with an error like this in the config.log
configure:8020: error: doxygen-pdf requires doxygen-pdf

[aportelli]

Have you tried --enable-doxygen-doc as in my original instructions?

[coppolachan]

ok thanks, looks working.
Minor thing: if I modify a file the make doxygen-doc does not recognise the modification and insists that the html is up to date.

I think you can move to the develop at this stage anyway.

[aportelli]

Hi Guido I missed that for 0.6, I will merge it with develop and close the issue.