The ABC's of Google

A is for Android
B is for Buzz
C is for Chrome
D is for Docs
E is for Earth
F is for Finance
G is for Groups
H is for Health
I is for Instant
J is for jQuery
K is for Knol
L is for Latitude
M is for Maps
N is for News
O is for Orcut
P is for Profile
Q is for Quick Search
R is for Reader
S is for Search
T is for Talk
U is for Uncle Sam
V is for Voice
W is for Webmaster
X is for XMPP
Y is for YouTube
Z is for Zitegeist

Automated Documentation Generation

When it comes to projects that I am working on, I tend to love tools that help me develop better software.  My favorite open source developer website is Ohloh, which provides insights into code statistics.  Since my projects are hosted on Google Code and Github the code browsing, issue tracking, and wiki pages are already covered. The missing link has been generating the source code documentation such as Javadocs.

All of my projects are hosted in a Subversion of Git repository, so it is just a single command to get the most up to date code.  Generating the documentation on my server allows for an automated approach to get up to date documentation on by website.

A few of my projects are written in Java, so generating Javadocs is exactly what I did.  The difficulty in this task was getting my server to compile the Android and App Engine projects.  After some tinkering, I managed to get the correct files and configuration set up on my server.  When executing the Javadoc command, it is necessary the the project be compiled.  This documentation is excellent and matches the standard for almost all Java projects.

I also have a few open source PHP web application that I have created.  For these projects, phpDocumentor provided a method to generate documentation that is similar to Javadocs, but is specifically geared towards PHP.  The documentation for these PHP applications is not as robust as Java, mainly due to the nature and design of the language.  My PHP based projects are lacking in function and class header information making these documents less useful.  In the future I may find some time to work on refactoring and fully documenting these projects.

Lastly, I have some open source C# applications.  These applications are the best documented applications because of my use of StyleCop which enforces strict coding standards.  Older versions of Visual Studio had built in functionality to generate HTML documentation.  This has replaced with NDoc, which has been replaced with Sandcastle.  These solutions had the major downside of only running on Windows, my website runs on Linux.  Based on the limitations of these other approaches, I went with Doxygen to generate C# documentation.

Doxygen is capable of generating html based documentation from a variety of languages without the need to compile the code.  After some customization, Doxygen generates robust HTML based documentation.  While it would be possible to generate the Java and PHP documentation using Doxygen, it is not as a tuned approach for those specific languages.  For the specific requirements of documenting a C# application, it is the best solution.

The current implementation generates new documentation for my opensource projects every night based on a single script.  My next goal is to write some logic that checks for updates every night, but only regenerates the documentation if there were changes made to the source.  Overall I am very pleased that I have found a solution for all of my projects and will continue to work on improving my commenting and documentation practices.