Writing documentation for a large ``C++'' project without a proper tool can be a daunting task. Unable to find a tool I liked, I decided to write my own, based on the following guidelines:
Documentation should be located as close as possible to the source. If not, the two diverge at a rate proportional to their distance. Source code documentation should reside in the source file, documentation related to a directory in files in that directory, and so on.
A large project does not reside in a single directory. It is made of many files in different directories which contain libraries, programs, utilities, scripts and data. Instead of viewing this structure as a nuisance, d4c&b regards it as invaluable and builds a similar directory structure for the documentation. d4c&b requires that a project has a single root.
Although the class is the focal point of a ``C++'' program, a large project typically uses other features of ``C++'' and other languages as well. d4c&b handles ``C++'', tcl, bison (yacc), flex (lex), texinfo and application specific files, provided they are simple enough.
d4c&b never documents anything automatically. You can hide methods, classes, files etc. if you think they are of interest only when reading the source code itself.
When source files change, d4c&b needs to re-process only files that have actually changed. This results in fast updates and good scalability.
Documentation is text based, so you need nothing more than your favorite editor. Hopefully it encourages adding documentation at the same time new code is written.
Since d4c&b documentation is made of text inside source files, it's visual effect should be small as possible. It gets noticed more and more when more advanced features are used, but it is always readable. (well, almost always ).
d4c&b generates an on-line document. Currently only HTML is supported, but since it's underlying language is a variant of texinfo, other output formats (from the same source) are possible.
d4c&b output is not fancy, and will not impress your manager. However, if it's a matter of font, size, or color, you might find a configuration option to change it. Personally, I find d4c&b mix of text, mathematical equations and simple figures [1] adequate, but your mileage may vary.
After reading the rest of this page, I suggest you take a quick stroll in src/d4cab to get a feeling what d4c&b output for ``C++'' looks like. Then read doc on how to write d4c&b documentation, and finally have a look at some of the source itself.
To view equations and special symbols, You need to fool Netscape into believing the symbols font is an iso8859-1 font. On Unix, you can try copying fonts.alias to your `fonts.alias' file, or create a new `fonts.alias' file in some local directory dir and add `xset fp+ dir' to your `.xinitrc' file.
Make sure document specific fonts are enabled. In my Netscape, it is under Edit|Preferences|Fonts
.
If that doesn't work, try Enabling Symbol Fonts in Netscape under X for other suggestions.
Do not let the presence of a configure script lull you into a false sense of security. d4c&b has only been tested on one operating system (Solaris 2.6) and one compiler (gcc 2.95).
d4c&b will use a workaround when this bug is detected, but if you have access to gcc, you might as well fix it.
From the top dirsctory,
d4cab> cd packages/flex-2.5.4 d4cab/packages/flex-2.5.4> configure --prefix=target-directory d4cab/packages/flex-2.5.4> gmake install d4cab/packages/flex-2.5.4> gmake distclean
d4cab> cd packages/tth_C d4cab/packages/tth_C> gmake d4cab/packages/tth_C> mv tth target-directory/bin
d4cab> cd d4cab d4cab/d4cab> autoconf d4cab/d4cab> setenv ... d4cab/d4cab> configure args --prefix=target-directory d4cab/d4cab> gmakeYou can have a look at the top `GNUmakefile' as an example.
d4cab/d4cab> gmake docdirs d4cab/d4cab> gmake docregendirsThe second run is needed only the first time, since the makefiles are set to generate documentation on a per directory basis, so a second run is required to resolve the cross references.
Later I might add a makefile target which will require just one pass.