Title: Members' Experiences

Doc++ is a program for generating documentation from C, C++ and Java code. Its use is similar to Javadoc, and it can create both HTML and TeX (for typesetting), like Web. It runs on most Unix systems, and can be compiled under Win32 with the GNU compiler. It is available for download from http://www.imaginator.com/doc++ and is included as a package in most Linux and BSD distributions.

Writing your source code with Doc++ in mind is simply a matter of inserting extra comments before the things you need to document. Doc++ comments are distinguished from other comments in that they begin with three slashes (///), or /** (/** is usually on a line of its own, and then the first line of the comment is treated as a summary). Insert these before any class, method, global function, variable, #define, enumeration and so on that you need to document, and in the comment put what you want to say about them.

Hierarchy is handled automatically, but if you need to group a few things together then you can create a Doc++ "scope" (which need not have any bearing on the program's scopes) with //@{ and //@} (or /*@{*/ and /*@}*/), and attach a Doc++ comment to it.

You can use a subset of HTML or TeX in the comments, and if you use HTML then it will be converted to TeX as necessary and vice versa. The HTML tags supported are P, EM, I, B, PRE, DL/DD/DT, UL/LI and LL/LI (other tags such as TT might have been useful, but perhaps they will be supported later). You can (if you need to) use TeX equations, and Doc++ will try to convert them to images for the HTML. You can also use Javadoc's tags @param, @return, @author and @see as in the following example:

@param x The X co-ordinate
@param y The Y co-ordinate
@return The distance from the origin
@author Me
@see SomeClass SomeIdentifier

One thing to bear in mind is that very occasionally there is ambiguity in what the Doc++ comments are referring to, and you may need to re-write the code slightly. For example, if a Doc++ comment were attached to

typedef struct { ... } x;

then it would be ambiguous whether it is referring to the struct or to x.

Doc++ source will of course compile as-is (it does not need to be "tangled" in the manner of the Web system), and generating the documentation is a matter of running doc++ with the right parameters. To try it out, I added some Doc++ comments to my access gateway source (and converted some of the existing comments into Doc++ comments), and tried converting it to HTML.

Unfortunately, the current version doesn't handle everything, especially if you specify -A (document All, i.e. including things that don't have Doc++ comments), in which case it gets confused by C++ files, and sometimes links to the sources instead of HTML. Best results are obtained by not using -A, and processing *.h before *.c++. Multiple /// lines don't always work well, overloaded functions are not handled (only the last function gets documented), and the anchors in General.html don't exist. Of course, this may all be fixed later.

If you have a Java-enabled browser, you can use an applet to view the class hierarchy. This could be useful if you prefer that way of working, but fortunately it is not a requirement.

The TeX output is well thought-out, although it is prone to wasting paper if you have a lot of identifiers with very little documentation (since at least one page is allocated to each). You have to run Latex in batch mode, otherwise it will stop you too often. Sometimes it outputs a mess. The contents are in the order of the source files; there's no way to sort it alphabetically but you can request the generation of an index. The "generate a complete source listing" option doesn't seem to work yet.

Overall, Doc++ shows promise, but at present it's probably best not to rely on it for showing your code to others in professional situations without checking its output first. As with other documentation systems, it is easier to begin a project with Doc++ in mind than it is to add it later.