C H A P T E R 16
■ ■ ■
Generating Documentation with
phpDocumentor
Remember that tricky bit of code? The one in which you treated that method argument as a string,
unless it was an integer? Or was it a Boolean? Would you recognize it if you saw it? Maybe you tidied it up
already? Coding is a messy and complex business, and it’s hard to keep track of the way your systems
work and what needs doing. The problem becomes worse when you add more programmers to the
project. Whether you need to signpost potential danger areas or fantastic features, documentation can
help you. For a large codebase, documentation or its absence can make or break a project.
This chapter will cover
- The phpDocumentor application: Installing phpDocumentor and running it from
the command line - Documentation syntax: The DocBlock comment and documentation tags
- Documenting your code: Using DocBlock comments to provide information about
classes, properties, and methods - Creating links in documentation: Linking to web sites and to other documentation
elements
Why Document?
Programmers love and loathe documentation in equal measure. When you are under pressure from
deadlines, with managers or customers peering over your shoulders, documentation is often the first
thing to be jettisoned. The overwhelming drive is to get results. Write elegant code, certainly (though
that can be another sacrifice), but with a codebase undergoing rapid evolution, documentation can feel
like a real waste of time. After all, you’ll probably have to change your classes several times in as many
days. Of course, everyone agrees that it’s desirable to have good documentation. It’s just that no one
wants to undermine productivity in order to make it happen.
Imagine a very large project. The codebase is enormous, consisting of very clever code written by
very clever people. The team members have been working on this single project (or set of related
subprojects) for over five years. They know each other well, and they understand the code absolutely.
Documentation is sparse, of course. Everyone has a map of the project in their heads, and a set of
unofficial coding conventions that provide clues as to what is going on in any particular area. Then the
team is extended. The two new coders are given a good basic introduction to the complex architecture
and thrown in. This is the point at which the true cost of undocumented code begins to tell. What would