Doxygen is easy to use and very powerful
While assembling this site, I discovered YACT (yet another cool tool!) Doxygen can create documentation on the fly for large source code bases, and can make navigating large code bases easier. I spent almost zero time to get a basic output that produced a really nice set of HTML pages documenting the drupal code base that drives this site.
Doxygen relies on simple tags in the source code to provide comments and function declaration descriptions. Check out the man page or Doxygen Home Page for more details.
Here is what I did:
Doxygen is driven from a configuration file. From the top level directory of the project, I asked doxygen to produce a template config file for me:
$ doxygen -g dp-config
This produce a 1200+ page template, but luckily most of the content wss descriptive text. Each configuration directive contains an explanation of what it does. It took only very minor modification to produce a useable config.
I changed only three config directives as follows:
PROJECT_NAME = Drupal
OUTPUT_DIRECTORY = ./docs (I created this subdir within the project to hold the doc files)
RECURSIVE = YES (Allow doxygen to traverse your source tree.)
From there, I ran the doxygen tool itself:
$ doxygen dp-config
And it produce 1.5 megabytes of HTML-based and latex docs.
I'm sure it's much more powerful than that, but what I got was what I needed -- a very useful listing of functions and files with corresponding function documentation.
Try it on your favorite project! It's worth the effort to learn it.