Doxygen is a great tool for turning C++ code and comments into reference documentation. We would absolutely love to use Doxygen in the ConceptGCC standard library, and in other libraries that are using Concepts in C++, but there’s one big snag: Doxygen doesn’t parse concepts, or requirements clauses, or any of the new constructs introduced into C++0x.
We’re looking for someone willing to implement C++0x support into Doxygen, so that we can produce great reference documentation automatically for ConceptC++ code. Having this functionality would be a huge benefit for C++0x and concepts. Any takers?
April 28, 2007 at 2:27 am |
Certainly a worthwhile project; Doxygen’s great, C++0x will be a huge improvement on C++98, and it would be great for them to work together.
I’m vaguely considering whether I can make time to work on this. It’s a fairly large project; Doxygen’s rough-and-ready almost-parser would need to be extended (first to just skip over concept-related things, later to process them), there would need to be new data structures to hold information on concepts and concept maps, and then the conversion support to weave/render HTML, XML etc. It would be nice to show refinement relationships between concepts too.
I’ve used Doxygen extensively, but never had to modify it. I’ll have a look. It does at least have some documentation for its internals.
April 28, 2007 at 11:53 pm |
There’s more to it than just concepts, of course; handling >> for closing template parameter lists shouldn’t be too difficult. It’s almost trivial (there’s code in Doxygen’s scanner.l to do something similar for Java and C#) except for the need to handle examples such as ct<(1>>0)> where the >> does not terminate the template list.
We should also check the preprocessing changes (vararg templates), support for raw string literals (which might be interesting, depending on how the lexing is handled), vararg templates, and who knows what else. But hey, I’ve started looking at some of this. Better put it under local version control for now.
April 30, 2007 at 7:27 pm |
To continue my conversation with myself… it’s not necessary (because it’s not practical) to make Doxygen parse all such things flawlessly. In general that needs the ability to tell if a name is bound to a template so that uses of < as an operator can be distinguished from uses as a delimiter. And that requires the ability to instantiate templates, perform overload resolution, evaluate a suitable range of constant expressions, … in short, parsing this part of C++ reliably means implementing half of a full front-end, which is not a good match for Doxygen’s pretty reasonable simplified parser.
May 1, 2007 at 11:07 pm |
I’ve been hacking (or rather trying to hack) Doxygen and the stuff doesn’t look good. The code’s messy and poorly designed to say the least. There are huge code couplings. So far I’m trying to do some reverse engineering. But there are no other options left, unfortunately. Unless you want to start a project from scratch (which I personally don’t consider a bad thing).
May 2, 2007 at 12:01 pm |
Starting a project from scratch would be a bad idea. One of the most important reasons for using Doxygen is that it is used by many, many projects… extending it for C++0x means that, as those projects evolve to use C++0x, their documentation system still supports them.
Doxygen has mailing lists where others have submitted various tweaks to the parser and layout for other languages. If you get stuck on a particular point, you could ask there for some pointers.