Languages

I needed a documentation generator primarily for PHP. However, I thought it’d be nice if it’d create documentation for JavaScript as well.

Possible Options

1. PHPDocumentor

   Formerly called PHPDoc, PHPDocumentor was my first choice because I’ve heard of it before. It’s based on JavaDoc, and is conveniently packaged in PEAR. The syntax is a little weird at first, and documenting blocks of code inline doesn’t seem to be possible. However, it figures out a lot of useful stuff. PHPDocumentor, of course, doesn’t work with JavaScript. Despite the lacking feature, this is document generator I implemented.

2. HeaderDoc

   HeaderDoc is Apple’s documentation system. It works with both PHP and JavaScript (as well as several other languages). I browsed the documentation, but haven’t bothered downloading the PERL code to compile it. I skipped on it because it seems far too robust (that is, bloated) for what I need and lacked some of the niceties of PHPDocumentor (e.g. detecting function names).

3. Natural Docs

   I was really excited about Natural Docs when I first heard about it. The syntax seemed easy and it was supposed to understand inheritance, which would be a boon for JavaScript. Unfortunately, JavaScript and PHP are only supported insofar as they can be read in the document. No nifty features like they have with ActionScript, PERL, and C#. Too bad.

4. Others

   I briefly looked at a few others that supported PHP and JavaScript. RoboDoc has fugly syntax and TwinText is supposedly Windows only (assuming it existed). Neither were going to be right for me.

PHPDocumentor in Use

Install

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.

Learning

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.

Output

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.

Final Opinions

PHPDocumentor is a pretty nice tool. Not only does it create documentation, it introduces a standard for commenting that is very legible. While I wish I cold have found a JavaScript and PHP document generator that I was happy with, PHPDocumentor does its job well.