Pro PHP- Patterns, Frameworks, Testing and More

(^62) CHAPTER 6 ■ DOCUMENTATION AND CODING CONVENTIONS
The easiest way to get the phpDocumentor parser tool is to install it from PEAR:
pear install PhpDocumentor
You will now have access to the phpdoc command. A good first try is this:
phpdoc -f somefile.php -t /path/to/output/directory
I suggest that you make the output path in your web root so that you can view the result
from your web browser. The phpdoc command offers a lot of output options, such as the following:

• HTML:frames:default, for HTML frames output


• HTML:Smarty:default, for Smarty template output


• CHM:default:default, for Windows help file format


• PDF:default:default, for PDF output

You may specify these options with the -o option using the following format:

output:converter:templatedir

Using the -h option will show you all the options and arguments.

After you have run the phpdoc command, you will find an HTML file in the output direc-

tory. This file can be viewed with a web browser and will contain information about the code

contained in your PHP file. I suggest you try some different combinations of the previously

discussed tags and see how they affect the output.

Once you have your documentation working the way you want, you may wish to extend

the PHPDoc tags. Although the phpDocumentor parser won’t use them, you can define any

otherwise unused tags and formats. When you build your own reflection parser, as described

in the next chapter, you will be able to parse these custom tags to do whatever you wish. An

example of a custom tag might be @lastmodified 01,23,2045. There really is no limit to what

you might include in your application.

DocBook

You may need to create comprehensive documentation that would not be sensible to include

in-line with your code. For example, some documentation may require examples or tutorials to

fully understand. In these cases, PHPDoc is not as appropriate as DocBook.

DocBook is designed to create documentation that is readable and comprehensive. In

practice, PHPDoc and DocBook are often used together harmoniously.

Creating an XML File for DocBook

DocBook is an XML application, just as XHTML is. It has elements and attributes, as you would

expect, and it follows a specific Document Type Definition (DTD); that is, it has defined rules

that translate the data at parsing time. DocBook uses Extensible Stylesheet Language (XSL) and

stylesheets to transform the DocBook XML into a presentation format.

McArthur_819-9C06.fm Page 62 Friday, February 22, 2008 8:59 AM