Posted by
Cliff
on from the user-testimonials-wanted dept.
bridgette asks: "I'd like to have a good 'javadocs-like' documentation generator for my C/C++ project. I've been looking into Doc++ but I haven't seen any 3rd party reviews. Anyone out there want to share their experiences with Doc++, good bad or otherwise? Anyone know of any alternatives?"
I used doc++ for a small C (not ++!) library recently. It really needed equation support in both printed and HTML docs. Doc++ was the only system I found to provide this.
Overall I was happy with it. My tips would be:
- subscribe to the developers list even as a non-developer. Bugs are introduced, and fixed, on a frequent basis.
- automake targets for this kind of thing are still mildly tricky. That's not doc++'s fault.
- the TeX layout looks pretty good, but tinkering with it requires at least a lesser TeX wizard.
- the code uses multiple state machines written using flex and C++. Check it out, it's pretty funky.
I looked around for a similar thing for my own project, and Doxygen was the best I found. Very full featured, and it can generate HTML, PDF, PS, LaTeX, even XML (sort of) from the same comments.
I highly recommend it.
-- Let's try not to let fact interfere with our speculation here, OK?
I looked at both DOC++ and Doxygen, and went with Doxygen. The benefit of not having to use Java to browse the class heirarchy, plus support for legacy C code, was a major plus for me.
I started with doc++ for my projects but later switched to scandoc.
The main con about doc++ (IMHO) is the lack of configurability of the output look and feel.
While scandoc will generate only HTML output (and you should look for other tools if LaTeX, TXT, Groff, your-format-here output is desired), it is very configurable, requiring some Perl hacking to get the template to generate what you want.
I've used Doc++ for a C/C++ project and was very impressed. Anyone who has used javadoc will be able to use this instantly; the doc++ commenting standard is a superset of javadoc. In addition, the speed is about an order of magnitude faster than javadoc.
Only a couple problems:
I had a few issues with Latex/TeX layout, but the html output is great
it is a pain to comment structs in C, because it forces you to define the struct without a typedef
I'd almost say its a better javadoc than javadoc, but I really like the doclet idea, even though it hasn't been fully exploited yet.
Slashdot Mirror
I used doc++ for a small C (not ++!) library recently. It really needed equation support in both printed and HTML docs. Doc++ was the only system I found to provide this.
Overall I was happy with it. My tips would be:
- subscribe to the developers list even as a non-developer. Bugs are introduced, and fixed, on a frequent basis.
- automake targets for this kind of thing are still mildly tricky. That's not doc++'s fault.
- the TeX layout looks pretty good, but tinkering with it requires at least a lesser TeX wizard.
- the code uses multiple state machines written using flex and C++. Check it out, it's pretty funky.
I looked around for a similar thing for my own project, and Doxygen was the best I found. Very full featured, and it can generate HTML, PDF, PS, LaTeX, even XML (sort of) from the same comments. I highly recommend it.
Let's try not to let fact interfere with our speculation here, OK?
The main con about doc++ (IMHO) is the lack of configurability of the output look and feel.
While scandoc will generate only HTML output (and you should look for other tools if LaTeX, TXT, Groff, your-format-here output is desired), it is very configurable, requiring some Perl hacking to get the template to generate what you want.
Here is an example of scandoc-generated documentation.
Only a couple problems:
I'd almost say its a better javadoc than javadoc, but I really like the doclet idea, even though it hasn't been fully exploited yet.