This tutorial deals with the PHP programming language.
HeaderDoc will work on most languages. It assumes you have some Linux experience.
Instead of using the cron daemon for Mac or Linux you can use the windows task
scheduler for scheduling program execution as detailed in the tutorial.
Introduction
If you have been part of a large development effort or
strive to keep your source code documentation up to date then you have
undoubtedly experienced difficulties. Documentation can quickly become out of
sink with the source code you are creating. There is often not enough time to
update the documentation to reflect the source codes current status. Apple's
Open Source HeaderDoc is an excellent solution to these problems. HeaderDoc
usage outlines a simple syntax for commenting and provides scripts to generate
the HTML documentation from your comments.
HeaderDoc Background
HeaderDoc is a “tool for generating HTML reference
documentation from comments in headers, and source code...”. HeaderDoc
facilities an easy to adopt coding standard and will generate detailed
documentation to construct a table of contents and individual pages for classes
and functions. A typical table of contents appears as detailed below:
Figure 1. Documentation Table of Contents.
If you were to click on the 'Database' link under 'Classes'
a new page would be presented that provides details about the class as shown below:
Figure 2. Class Documentation
This is very helpful and generated automatically. Lets get
it setup on your system!
HeaderDoc Configuration
If you do not have an Apple ID sign
up for one now. It's a free account that grants you access to all the Apple
Developer projects which includes numerous utilities and scripts. Most will run
on platforms besides OSX including Windows and Linux.
Next visit the HeaderDoc home page and download the latest version HeaderDoc 8.0. HeaderDoc requires you
have Perl installed. For Mac OSX and Linux users Perl is usually installed by
default. You can download the source, binary or rpm from the Perl website. Windows users can
grab the Perl binary from the Perl website as well.
Once your account is setup and you've downloaded HeaderDoc
move it to your home directory and extract it.
Issue the following commands to extract the HeaderDoc files:
[sk@projectskyline
~]$ gunzip headerdoc-8.0.tar.gz (unzip the file)
[sk@projectskyline
~]$ tar -xvf headerdoc-8.0.tar (extract the files and create a directory
/headerdoc-8.0)
There is no installation script to run. It is just as simple
as extracting the files. You are now ready to add HeaderDoc comments to your
code and generate documentation.
HeaderDoc Syntax
For HeaderDoc to work properly your comments must follow a
specific syntax. Lets look at an example of a commented header below:
<?php
/*!
@header Database
Handles all database queries, connections and errors.
@copyright
Copyright (c) ProjectSkyLine LLC with operations in NH & NY,
2005-2007.
*/
The difference between a standard comment and the HeaderDoc
style is simple. The first is the '!' exclamation point following the comment start. Next is
the required @header and @copyright keywords. Comments within the /*! .... */
are parsed by HeaderDoc for @keywords.
Comments may span multiple lines and include any characters.
However you must escape the @ ampersand by providing a backslash \ in front of
it such as \@, to include it in a comment.
Lets look at the HeaderDoc commenting for a database class:
/*!
@class Database
@discussion Handles all the database operations.
*/
class Database
{
Again the syntax is very simple. We introduce the @class
keyword and the @discussion keyword. Both keywords are required for a class
definition.
Last we look at the function syntax:
/*!
@function Database
@discussion Constructor creates the database handle and attempts
to use the provided database.
@param debugBool TRUE to turn on error logging for ALL sql queries.
This includes the sql string and the execution time.
@param dbUserStr The name of the database user.
@param dbPassStr The password for the database.
@param dbNameStr The name of the database.
@result Returns a valid database handle attached to the provided
database.
*/
function Database($debugBool, $dbUserStr, $dbPassStr, $dbNameStr)
{
This function declaration is more complicated than the
previous so lets examine it line by line. The first keyword @function lets us
provide a name for the function. The next keyword @discussion is used in the
previous examples. The @param keyword is introduced to provide a way to
describe this functions arguments. The @param keyword follows the format:
@param
<Argument> <Description of Argument>
@param
dbUserStr The name of the database user.
Also introduced is the @result keyword which details the
return value of this function.
Executing HeaderDoc Scripts
Generating the documentation is the easiest and best part of
HeaderDoc. You will be working with two scripts, headerDoc2HTML.pl and gatherHeaderDoc.pl.
The first, headerDoc2HTML.pl, creates the html comments page from each
header file. If you include a headerDoc comment in each .php file then the
script will create a matching index.html.
For example, creating a HeaderDoc comment page by running headerDoc2HTML.pl for
OOPLIB/DBAS/DBAS.php
would yield
OOPLIB/DBAS/Classes/Database/index.htm
for the database class example above. headerDoc2HTML.pl will create a top level table of contents html file, such as
OOPLIB/masterTOC.html. Ideally you want your documentation to be as up to date
as your code. This can be accomplished by automating the task with a cron job
on Linux / Mac or task scheduler for Windows.
Automating Documentation Creation
To automate creation of the documentation we will create a Cron Job that runs every day and
creates all the index.htm files for all classes and the master table of
contents file.
Lets take a look at this example crontab entry:
0 */12
* * * /home/sk/headerdoc-8.0/headerDoc2HTML.pl /var/www/html/OOPLIB/
0 */24
* * * /home/sk/headerdoc-8.0/gatherHeaderDoc.pl /var/www/html/OOPLIB/
The first command:
0 */12
* * * /home/sk/headerdoc-8.0/headerDoc2HTML.pl /var/www/html/OOPLIB/
will execute the headerDoc2HTML.pl file recursively on the
/var/www/html/OOPLIB/ directory every 12 hours of every day and create the
class documentation for each library file that includes headerDoc comments.
The second command:
0 */24
* * * /home/sk/headerdoc-8.0/gatherHeaderDoc.pl /var/www/html/OOPLIB/
executes the headerDoc.pl recursively on the
/var/www/html/OOPLIB/ directory once a day and creates the table of contents file.
To edit your crontab issue the following command:
[sk@projectskyline
~]$ crontab -e (invokes an editor to edit the crontab file)
and place the lines in from above, substituting your home
directory and target directory.
If you completed the setup without errors you will have
detailed and up to date documentation for your source code updated every day.
If you have questions or comments please contact me.
References
System information
This tutorial was conducted on Fedora Core 5 Linux kernel
2.6, Perl version 5.8.8.
Ben Sgro is the chief engineer and co-founder of ProjectSkyLine
LLC, a full service software company that provides web development, graphic
design, application programming, identity standards internet marketing and
security. ProjectSkyLine has just released their premier product, Project-Contact, a full-featured
RSVP management application for web use. If your company needs a custom
solution please contact Ben or anyone on the ProjectSkyLine team at http://www.projectskyline.com.
|
