CHAPTER 16 ■ GENERATING DOCUMENTATION WITH PHPDOCUMENTOR
otherwise have been a few weeks of acclimatization soon becomes months. Confronted with an
undocumented class, the new programmers are forced to trace the arguments to every method, track
down every referenced global, check all the methods in the inheritance hierarchy. And with each trail
followed, the process begins again. If, like me, you have been one of those new team members, you soon
learn to love documentation.
Lack of documentation costs. It costs in time, as new team members join a project, or existing
colleagues shift beyond their area of specialization. It costs in errors as coders fall into the traps that all
projects set. Code that should be marked private is called, argument variables are populated with the
wrong types, functionality that already exists is needlessly re-created.
Documentation is a hard habit to get into because you don’t feel the pain of neglecting it
straightaway. Documentation needn’t be difficult, though, if you work at it as you code. This process can
be significantly eased if you add your documentation in the source itself as you code. You can then run a
tool to extract the comments into neatly formatted web pages. This chapter is about just such a tool.
phpDocumentor is based on a Java tool called JavaDoc. Both systems extract special comments
from source code, building sophisticated application programming interface (API) documentation from
both the coder’s comments and the code constructs they find in the source.
Installation
The easiest way to install phpDocumentor is by using the PEAR command line interface.
pear upgrade PhpDocumentor
■Note In order to install or upgrade a PEAR package on a Unix-like system, you usually need to run the pear
command as the root user.
This will make a network connection (to http://pear.php.net)) and automatically either install or
update phpDocumentor on your system.
You can also download the package from SourceForge.net at
http://sourceforge.net/projects/phpdocu/files/. You will find zipped and tarballed packages here.
Once you have the package on your file system, you may be able to install it directly using PEAR if PHP
was compiled with zlib support.
pear install PhpDocumentor-1.4.3.tgz
Alternatively, you can uncompress the archive and work with phpDocumentor directly from the
distribution directory. The command line interface is handled by the file phpdoc, and you need to have
the library directory phpDocumentor in your include path.
tar -xvzf PhpDocumentor-1.4.3.tgz
cd PhpDocumentor-1.4.3
chmod 755 phpdoc
./phpdoc -h
Here, I unpacked and entered the distribution directory. I made the phpdoc script executable and
ran it with the -h flag, which calls up a usage message.
If you have any problems with installation, the phpDocumentor package includes a file named
INSTALL, which contains extensive instructions and troubleshooting hints.