Developers and documentation are like oil and water—they
just don’t mix well. Many developers find writing documentation to be a boring waste
of time. It’s no wonder, then, that most companies hire separate personnel to
create technical documentation rather than try to persuade developers and
programmers to do it themselves.
But for those of you developing with PHP, there is a solution
called phpDocumentor. Similar
to Java’s javadoc
tool, phpDocumentor automatically creates API documentation by reading special
identifiers and comments embedded in your PHP code. Since most good developers
routinely use comments in their code anyway, the additional burden on them is
minimal. And phpDocumentor can output its documentation in a variety of formats
(including HTML, XML, and PDF), further reducing the time spent on manual
documentation. Of course for more sophisticated documentation like user manuals
or process flow diagrams you still need a technical writer. But for simple
class documentation and method prototypes, phpDocumentor is a very adequate
In this crash course, I’ll start by showing you the special
identifiers and syntax you can use when marking up your scripts. I’ll also show
you the basics of using phpDocumentor to read your code and automatically
generate a class tree and method/property information from it.
A complete solution
Billed as “the complete documentation solution for
PHP”, phpDocumentor works by reading your source code for comments and then
using those comments to create professional, neatly-formatted API
documentation. It supports a variety of different output formats: HTML, PDF,
Windows HLP, and XML. Within each of these output formats, different templates
and designs are available. And you can even create your own templates—phpDocumentor
uses the well-known Smarty
template engine to render the data.
phpDocumentor is available through
PEAR, the PHP Extension and Application Repository, and it can also be downloaded
from Phpdoc.org. To install it,
simply extract the files in the download archive to your local installation of
PEAR and point your browser to the phpdoc.php script in the installation
directory. You should see something like Figure
|Primary Web interface to phpDocumentor|
This form is the primary Web interface to phpDocumentor
(there’s also a command-line interface, but we’ll focus on the GUI), and you’ll
use it to tell the application which PHP classes to read and generate
documentation for. More on that later, though—first, let me show you how to use
phpDocumentor syntax to mark up your code.
Turning up the heat
Consider the simple function definition in Listing A.
This code is a PHP function definition, with both arguments
and a return value. To have phpDocumentor generate documentation from this, you
need to mark it up with some more information, as show in Listing B.
Sure, it looks impressive…but what does it actually mean?
The basic element of phpDocumentor markup is a so-called
DocBlock—a multiline comment block—which can appear before any PHP construct,
class, or function and looks like this:
* text here
Within this DocBlock, phpDocumentor allows three types of
items: a short description; a longer description; and a series of special tags
each prefixed with an @ symbol as in the example in Listing C. These tags are optional; however, it’s a good idea to
include them to help make the final documentation more precise. Some of the
more commonly-used tags supported by phpDocumentor, and what each represents:
@access: whether the function is private or public
@author: the name and e-mail address of the function author
@version: the version number of the function
@copyright: copyright information for the function, if needed
@package: the package the function belongs to, if available
@param: argument to a function, including its type and a description
@return: return value from a function, including its type and a description
@var: the variable type and description, for class variables or local variables
inside a function
@global: the variable type and description, for global variables inside a
@see: name of another, related element
@todo: items still to be completed
There is no hard and fast rule about which tag appears
where, but a general rule of thumb is to use only relevant tags to avoid
cluttering up the final document. For example, it makes sense to use @param and
@return for functions and methods, but is inappropriate to use these two tags
for variable definitions. The phpDocumentor Web site offers more detailed guidelines.
Many hands make light work
Now that you’ve got your code all marked up in phpDocumentor
syntax, it’s time to use it. Pop open your browser and head back to the
phpdoc.php form you saw earlier. This time, go ahead and fill the form out—you
must enter values for the target directory (where the documentation will be
placed), the source directory or source file (what is to be documented), and
the output format or “converter” to use (I usually choose
HTML:Smarty:PHP). Once you’ve filled those in, submit the form and
phpDocumentor will go to work generating the document.
A few hundred status messages later, you should have the
documents generated and placed in the target directory. Navigate to that
directory and open the index page in your browser to see something like Figure B.
|HTML output of phpDocumentor|
You can click on the filename in the left frame to view its
contents, Figure C.
|Documentation generated from a user-defined PHP function|
Notice how all the information you provided in your tagged
source code has been converted into a neatly-formatted API definition. Now
let’s see how this works with classes and class
Back to class
The amount of documentation needed for the source code of a
class is much more than that needed for a simple function. Typically, you will
place class-level information above the class definition, and include author,
version, and copyright information in the outer DocBlock; you can also include
the @package tag if this class is part of a larger package. Class variables are
usually marked with @var tags for data types and @access tags for private or
public visibility, while class methods use @param, @return and @access tags to
represent method arguments, return values, and visibility respectively.
When you run phpDocumentor on the class definition, you should
get something like Figure D.
|Documentation generated from a PHP class|
The source code of the class has been neatly dissected.
There’s a section for the class overview, a list of private and public
variables, methods and method prototypes, and other useful information.
Documentation like this makes it easy for other programmers to quickly
understand what your class does and how it works—and how to use it without
having to dig through the actual source.
If you’re an OOP programmer, it’s unlikely that you’ll be
using stand-alone classes. It’s far more likely that you’ll have a class
hierarchy, where objects serve as the base for new child objects with new and
inherited properties and methods. phpDocumentor excels at building
documentation for this type of class tree—it has built-in support for
identifying dependencies between classes, and for creating links between the
different hierarchies of a class API.
To understand this better, consider the extension of the
AddingMachine() class shown in Listing E,
and then look at some screens of what the generated API looks like (Figure E and Figure F).
|Basic documentation generated from a PHP class|
|Detailed documentation generated from a PHP class|
Notice how phpDocumentor has cleverly figured out that the
Calculator() object is a child of the AddingMachine() object from the
“extends” keyword, and has imported and linked AddingMachine()
methods and properties into Calculator()’s namespace.
phpDocumentor also comes with a bunch of tags that can be
used to point a reader to additional reference material, or to related classes
and functions. The simplest of these is the @see tag, which tells the reader to
“see” related variables, functions, or classes. The code in Listing F demonstrates its usage.
The debit() and credit() functions will be linked to each
other in the final documentation, making it easier for users to jump from one
to the other. You can create as many such @see links as you like—phpDocumentor
will automatically attempt to track down the target variable or function and
create a link to it.
If you’d like to link to a Web page or tutorial describing
the element in greater detail, use the @link tag, which is automatically
converted by phpDocumentor into a hyperlink. Listing G shows how to use the tag.
When phpDocumentor encounters the @link tag in Listing G, it
will create a hyperlink to the URL argument. This is great for linking to more
detailed documentation elsewhere, or for putting notes and tips in your classes
that can be explained in detail later.
I hope this article gave you enough information to get you
started with this auto-documentation system. But this is just the tip of the
iceberg. There are many more things you can do with phpDocumentor, and you can
read all about them in the excellent online tutorial. I hope you’ll take advantage of
phpDocumentor’s powerful features to save yourself some time and stress the
next time you sit down to code a PHP application.