Source Code documentation is an often neglected aspect of Software Engineering. In most software projects, an overview of the code structure is useful both for new developers looking at the code for the first time, as well as a reference for all developers interacting with this code.
Fortunately, there are many useful tools to help us with this issue, namely, Code Documentation Generators. These tools pick up the code’s structure through syntactic parsing and typically augment it with information supplied by the developers directly in the source code. In the last step, a nice HTML-based reference manual is typically exported.
The following sections present some interesting examples of this type of tool.
“Doxygen is the de facto standard tool for generating documentation from annotated C++ sources, but it also supports other popular programming languages such as C, Objective-C, C#, PHP, Java, Python, IDL (Corba, Microsoft, and UNO/OpenOffice flavors), Fortran, VHDL, Tcl, and to some extent D.”
- How to extend Doxygen for other programming languages : http://www.stack.nl/~dimitri/doxygen/helpers.html
Screenshots of doxygen documentation:
- example of source code comments suitable for javadoc:
“YUIDoc is a Node.js application that generates API documentation from comments in source, using a syntax similar to tools like Javadoc and Doxygen”
- Sandcastle Help File Builder (SHFB)
A standalone GUI, Visual Studio integration package, and MSBuild tasks providing full configuration and extensibility for building help files with the Sandcastle tools