CHAPTER 16 ■ GENERATING DOCUMENTATION WITH PHPDOCUMENTORNotice that I didn’t need to tell phpDocumentor that the Command class is abstract. This confirms
something that we already know, that phpDocmentor interrogates the classes with which it works even
without our help. But it is also important to see that DocBlocks are contextual. phpDocumentor
understands that we are documenting a class in the previous listing, because the DocBlock it encounters
immediately precedes a class declaration.
■Note At the time of this writing, phpDocumentor does not support namespaces. However, the project’s
maintainer, Greg Beaver, is on record as committed to provide this functionality
(http://lists.bluga.net/pipermail/phpdocumentor-devel/2008-September/000066.html).
File-Level Documentation
Although I tend to think in terms of classes rather than of the files that contain them, there are good
reasons in some projects for providing a layer of documentation at the file level.
First of all, phpDocumentor likes file comments. If you fail to include a DocBlock for a file in your
project, a warning is raised that can clutter up the application’s reporting, especially in large projects. A
file comment should be the first DocBlock in a document. It should contain a @package tag, and it should
not directly precede a coding construct. In other words, if you add a file-level DocBlock, you should
ensure that you also add a class-level comment before the first class declaration.
Many open source projects require that every file includes a license notice or a link to one. Page-
level DocBlock comments can be used, therefore, for including license information that you do not want
to repeat on a class-by-class basis. You can use the @license tag for this. @license should be followed by
a URL, pointing to a license document and a description:
/**
- @license http://www.example.com/lic.html Borsetshire Open License
- @package command
*/
The URL in the license tag will become clickable in the phpDocumentor output.Documenting Properties
All properties are mixed in PHP. That is, a property can potentially contain a value of any type. There
may be some situations in which you require this flexibility, but most of the time, you think of a property
as containing a particular data type. phpDocmentor allows you to document this fact using the @var tag.
Here are some properties documented in the CommandContext class:
class CommandContext {
/**
- The application name.
- Used by various clients for error messages, etc.
- @var string
*/
public $applicationName;
/**