I’ve been looking at documentation generators recently. Specifically, I’m playing with a new website that I want to do Right. Here are some notes for anyone looking at PHP documentation generators.
PHPDocumentor in Use
As I mentioned, PHPDocumentor is a PEAR package. That made the install very easy. I actually overcomplicated it quite a bit because of a few errors I had with the script. For future reference, you want to run pear install PHPDocumentor-beta since PHPDoc is depreciated. One will override the other.
As I said, when I tried to run phpdoc, I got an error about a file missing. Mac OS X apparently stores files in different places than the package expects. So, I had to edit the package and add
chdir("/usr/lib/php/"); so that
include("PhpDocumentor/phpDocumentor/phpdoc.inc"); would be run in the proper directory.
Since I wanted to have my documentation as a sub directory of my site, I had to write a shell script to clean out my documentation folder then run the PHPDocumentor command. Otherwise, PHPDocumentor would attempt to document the documentation.
I was a little bewildered by the syntax at first. This is mainly because it’s really hard to find solid examples of how to document code. The manual provides a little bit of instruction, but lacks real world examples. Luckily, I found a good example in the PEAR coding standards documentation. It wasn’t long until the syntax was second nature.
The only real gripe I have is that I’d like to be able to make inline comments about specific blocks of code. For example, a
switch. It turns out that you have to do that within the function discussion. You can print code blocks in the discussion area, however. So, it’s almost as though you can do inline documentation.
I also should note that
@var can only be attached to a class variable declaration, not any variable at all.
I struggled with the output. I hate frames. So, I used the Smarty layouts for output at first. Eventually, I switched to the default frames layout because it handled some of the output better (e.g. unordered lists in discussions). Otherwise, it makes nice legible documentation that can be read on a web browser. It can also output PDF, and Windows Help files.