Software Architecture is largely a matter of communication. One big area of communications is documenting a library, whether for internal or external consumption. It is well-known that written documentation goes out of date the minute you publish it.

The only hope of keeping the documentation up-to-date is to have the it embedded within source code it is illuminating. This allows you to update the doc as you update the code. The Javadoc and C# XML comments are good for this, but don’t give you a good way to provide anything beyond documentation of classes and methods, which often falls short in properly documenting a library or code base.

Doxygen is a capable, open source library that combines the comment-based documentation with a full mark-up language that allows you to add text, diagrams, pages, sections, lists, etc. that allows for robust documentation.

Some of my favorite features include:

• Auto-generated class and collaboration diagrams
• The ability to include hyperlinked source
• Compiled Help format
• PDF format