Using doxygen to produce self-documenting source code.
Install doxygen http://www.stack.nl/~dimitri/doxygen/download.html#latestsrc. I had trouble with the Mac OS X version--the interface seems to need some work (9/2008), so I suggest installing from source. Download the source code and the, using the terminal
cd /path/to/doxygen
./configure
make
sudo make install
With the most current development tools, the code should compile cleanly.
Document the source code. There are numerous ways of doing this, all documented here. I propose that we use a standard style here that conforms to the javadoc syntax. Typically a comment will look like this:
/** <--doxygen comments begin with two stars (**)
This is the documentation here. This function doesn't do anything... Following the general description, a list of parameters, return values, etc. is given. The leading character before these keywords can either be a @ or a /. I propose using the @ since it is consistent with the javadoc formatting. A complete list of keywords can be found here.
@param foo After a param keyword, the name of the argument is listed ("foo" in this case) followed by a description of what that parameter does (what you're reading now).
@param bar Another one...
@returns The value that the function returns.
*/
float lameFunction(char foo, int bar){return 13.4;}
Create a config file. Run doxygen -g <config-file-name> to generate a file template. Each project that gets documented will have it's own configuration file. The basic config file is pretty reasonable, although some variables have values which need to be filled in.
Create the documentation. This is done by running doxygen <config-file-name> at the command-line. The documentation will be placed in the folder specified in the config file. Ultimately, I think we should automate this process, i.e. it will be done in the Makefile. I'm hoping that all of the resulting documentation will be collected in one spot and automagically hooked into the drupal site.
