CHAPTER 16 ■ GENERATING DOCUMENTATION WITH PHPDOCUMENTOR
Documenting Classes
Let’s add some more tags and text that are useful in class- or file-level DocBlocks. I should identify the
class, explain its uses, and add authorship and copyright information.
Here is the Command class in its entirety:
/**
- Defines core functionality for commands.
- Command classes perform specific tasks in a system via
- the execute() method
- @package command
- @author Clarrie Grundie
- @copyright 2004 Ambridge Technologies Ltd
*/
abstract class Command {
abstract function execute( CommandContext $context );
}
The DocBlock comment has grown significantly. The first sentence is a one-line summary. This is
emphasized in the output and extracted for use in overview listings. The subsequent lines of text contain
more detailed description. It is here that you can provide detailed usage information for the
programmers who come after you. As we will see, this section can contain links to other elements in the
project and fragments of code in addition to descriptive text. I also include @author and @copyright tags,
which should be self-explanatory. You can see the effect of my extended class comment in Figure 16–4.
Figure 16–4. Class details in documentation output