PHPXref vs PHPDocumentor

Introduction

There exists a wide array of PHP documentation tools on the web available free for download. Two of the most popular ones are PHPXref and PHPDocumentor. Here, I outline the differences between the two to help you decide which one you should use.

The following information was taken from http://phpxref.sourceforge.net/ and http://www.phpdoc.org/.

Similarities

The greatest similarity between the two tools is, of course, their ability to read PHP documents and output information about them in another format, namely HTML. Both of these documentors highlights elements of the source in order to increase readability. PHPXref has also adopted the PHPdoc commenting standard to give additional information about pages, while recent versions of PHPdocumentor has adopted PHPXref’s ability to cross reference source code.

The Strengths of PHPXref

  1. PHPXref is programmed in Perl which is directly run by your machine. In that way, it is potentially faster than PHPdocumentor which does the processing through PHP itself.
  2. The HTML output of PHPXref is very neat – it implements a bit of javascript to provide neat rollover visuals on additional information.
  3. Perhaps the strongest feature of PHPXref is its ability to provide information even without PHPdoc comments.
  4. Very easy to use and set up. You simply drag the files you want information about in a source folder, run the command prompt, and grab the documentation from the source folder.
  5. Although I haven’t tested it, PHPXref mentions that they provide information about SQL tables.

The Strengths of PHPDocumentor

  1. Provides both a web and a command line interface.
  2. Can output in CHM, HTML, and PDF!!
  3. The interface allows a lot more customization than PHPXref. It can generate the resultant documentation in your own web interface (or you can choose one of their pre-built ones) in addition to choosing the source directory and the output directory. This level of customization is really what makes PHPXref more difficult to use than PHPXref which decides those things for you.
  4. Has an active community with a well-detailed online documentation. #Can create class inheritance diagrams (Not tested)
  5. Their documentation IS the standard. Expect new features and updates.
  6. Bundled with Zend Studio, a popular web development software.

Summary

Perhaps the main reason to use PHPXref is its ability to provide information without PHPdoc comments. This ability gives PHPXref a speed advantage if you want quick documentation without having to go back and comment lines and lines of code (although you should consider getting around to it!). This type of development favors procedural programming to an extent.

Personally, I like PHPdocumentor’s ability to create PDF’s and its online documentation. Another cool feature is perhaps the ability to infer class inheritance straight from the source code. The rest of the features of PHPdocumentor is just eye candy.

Keep in mind that PHPdocumentor will have immediate support for PHPdoc style commenting. New versions of PHP may create a need for more commenting standards that PHPdocumentor will be quick to adopt.

I suspect that in the future, PHPdocumentor will continue to adopt useful features from other documentation tools. But in reality, the major differences between PHPXref and PHPdocumentor have been neutralized – using either one will likely suffice for your needs.