2 replies to this topic

[Wernaeh]

Hello everyone :)

What kind of tools do you use for documenting your (c++) software ?

Up to now, I've been using Doxygen, but I have several gripes with it. In particular, the documentation it generates IMHO is somewhat ugly and bloated, especially for some of the smaller-scale projects I was involved in recently.

I've already tried around with the user-provideable stylesheet, but it just improves things slightly - font sizes and those "My-First-Homepage"-like section buttons, mainly.

* There still are unnecessary back-indices of (member -> class or file), with one index page for each letter, and like 5 entries on each of these.

* I can't disable automatic link generation - which is a problem if you have got a namespace that has the same name as your project: You get backlinks all over the place, which you then need to manually suppress. I'd rather always tag classes when I actually want to have a link to these.

* ... and several more annoyances I just don't want to completely list.

I've already looked through the list of alternatives on the Doxygen homepage, but neither of these looks too promising - some of them aren't even in development anymore...

Perhaps I'm a bit spoiled by the niceties and cleanness of JavaDoc... but surely, there must be some viable alternative for C++ ? What other tools do you have experience in ? What customizing do you do to the Doxygen output ?

Thank you for your time,
Cheers,
- Wernaeh

[SmokingRope]

I *tried* to contribute a few patches to doxygen around version 1.5.7 or so. I'm not aware of any better alternatives for C++ documentation however you could always modify the doxygen source code to resolve some of your problems. I haven't seen any particular enthusiasm for patch acceptance on the mailing list so you may end-up having to maintain any changes you make yourself. On the other hand, if it's a bugfix and not feature enhancement you may have more luck.

Also, i haven't tried, however i believe the recommended method for customizing the html documentation is through post-processing in a perl script.

[Wernaeh]

Quote

Also, i haven't tried, however i believe the recommended method for customizing the html documentation is through post-processing in a perl script.

Thank you for the input. I've thought of something similar the past few hours... take Doxygen's XML output, and generate the required documentation via some write-once Perl script that can be used by the entire programming department. Anybody any idea on how much effort goes into such a script? - I'm not too firm with Perl's XML / HTML capabilities myself...

Cheers,
- Wernaeh