phpDocumentor is a really popular code documentation tool and format for PHP. But, it’s not the only tool. I was recently revisiting which tool I would use to document a project I was beginning. In the past I had used both Doxygen (with Drupal) and phpDocumentor. I expected to choose phpDocumentor and be on my way. But, after looking into both tools I ended up choosing Doxygen. Here are a handful of reasons that caught my attention and may catch yours as well.

Doxygen Is An Active Project

If you look at the activity on both projects there is a night and day difference. Doxygen is active with recent releases and commits.

phpDocumentor, on the other hand, looks like a dead project. The latest news posting is from March of 2008. That’s two and a half years ago. The only release since that time was a maintenance release that didn’t even get a news post. That was a year ago.

What about those new PHP features? I tried to look at the source and found the link on the website was dead. I went to the look at the bug system and got permission denied. The latest release doesn’t support the newer features and there doesn’t seem to be a place to even find the status.

Documentation on Documentation

When I first went to configure Doxygen and opened up an example config file I was blown away at the size of the file. It was well over 1,000 lines long and most of the file was comments. It may be the most well commented config file I've seen.

This sets the tone for the project. There is a lot of documentation and everything I found is fairly well explained. For someone not intimately familiar with the project I was up and running in a short amount of time and had an idea what I was doing.

This is not to say the documentation for phpDocumentor is lacking. I just found the documentation on Doxygen to be better.

Writing Pages of Documentation Is Easier

Not all documentation is contained in the source comments. Tutorials, about pages, and so much more can and should be written. These need a place to live and are good to have with the rest of the documentation.

phpDocumentor uses DocBook for this user level documentation. In some ways DocBook seems like a great idea. To have a XML format for the books to be stored in can have a lot of advantages. Unless you have to write it. I have yet to find a DocBook editor I’m happy with. And, writing documentation by hand as XML is no fun at all.

Doxygen handles documentation like this very differently. Pages are code comments, just like everything else. Instead of learning a different syntax (DocBook XML) you just need to learn a few new tags. For example:

/**
 * @page page_foo_1 This Is An Example Page Title
 *
 * lorem ipsum dolor sit amet, consectetur adipiscing elit. Integer risus nunc, lacinia vel blandit vitae,
 * egestas quis dolor. Maecenas nibh lectus, molestie quis accumsan nec, volutpat vel odio.
 *
 * @section section_bar_1 A Section Title
 * Nulla ipsum sapien, accumsan eget congue vel, euismod nec tellus. Etiam dictum velit vitae tortor
 * vestibulum non posuere leo fringilla.
 */

Note: DocBook output can be generated from documentation in Doxygen. Some projects already do this.

Search!

When it comes to reading documentation I'm a search junkie. Why read everything when you can search and find what you're looking for so much faster. Doxygen comes with two forms of search. There is a simple JavaScript based search and a PHP based search. To use this you just enable the search you want in the config file and Doxygen does the rest.

At this point, Doxygen looks like the clear leader between the two. Is there is already a heavy investment in phpDocumentor I don’t expect to switch a project from one to the other without a good reason. But, for new projects Doxygen looks like a leading candidate.