When I recently started getting serious about documentation I wanted to understand the state of PHP documentation tools. Our PHP libraries and applications should be well documented if we want others to be able to work with them (this includes team mates). The crop of documentation tools currently on my radar are:

• Sami: A recent addition to the documentation game and used to power the Symfony API documentation.
• phpDocumentor: What used to be the go to tool is starting to see new life in a 2.0 rewritten version.
• Doxygen: A multi-platform API documentation tool that supports PHP.

Let’s dive into these documentation tools.

Background and Fair Warning

To let everyone know of my background up front, I’ve been using Doxygen for years. I used to be a fan or phpDocuemtor but when it fell into a stale state for an extended period I looked for alternatives. Doxygen ended up being the tool I landed with. The state of things has changed in recent times which is why I’m looking at the options again.

Sami

Sami is literally the new kid on the block. The first commit was just two months ago (May 2012) and looks like the modern flavor of new PHP applications. Most of what powers it is other libraries managed by Composer. For being a PHP CLI application it was fairly fast at generating PHP API documentation for the HPCloud PHP library generating the documentation in under a second.

Some positives:

• Fast for a PHP CLI application. Significantly faster than phpDocumentor 1 was.
• Modern in its look (the code), development, and interaction with other libraries.
• Can generate documentation for multiple versions of a codebase using Git tags and branches for the versions.
• Is themeable through Twig.
• Easy to install. Especially if you already use modern PHP projects like this.

Each of these applications has strengths and weaknesses. There are some things I wish It could do:

• It would be great if you could write documentation pages as well as a code. Maybe an introduction page to the API, some tutorials, etc. This exists in other tools and is something I’m finding useful.
• Markdown support. It would be great to write docblocks with markdown and documentation pages in markdown. This was an addition to other tools I didn’t know I needed but has learn to really appreciate.
• Pretty graphs of the dependency chains.

Of all the documentation tools for the PHP community this one might have the brightest future. I look forward to a 1.0 release and to see where it can go from here.

phpDocumentor

I used to think phpDocumentor was a dead project. When the new features came to PHP I was forced to look elsewhere. The old version of phpDocumentor was slow. I used to treat it like I did with compile steps and go do something else while the documentation generated. But, the project has gotten new life and a 2.0 version is on the way.

Some positives:

• A responsive design by default. It uses bootstrap and is responsive out of the box. While this is sometimes a double edged sword as too many sites are starting to look like default bootstrap, it totally works here.
• Much faster than it used to be. While it did take about 8 times longer than Sami or Doxygen to run it was fairly fast for me. Thought, if Sami did as much as phpDocumentor I would expect it to be slower.
• There is a report of undocumented stuff. If variables on classes, methods, or other elements are undocumented it provides a report. This can be quite handy in looking at documentation coverage.
• Markdown support in DocBlocks.

Some areas I would love to see improved:

• The installation process was kind of a pain and the worst of the 3. Part of the reason could be that it uses Pear. I had to jump through some hoops to make everything work and sort out a couple errors.
• While it is templatable this system is not for front end developers.
• Just like Sami, it would be nice to have documentation pages.

Doxygen

Doxygen is a tool for documenting code that happens to support PHP. It can be used to document other languages such as C, Python, and others. Of the 3 options I think Doxygen provides the most features but is also the most complicated. For the amount of work it does it does so at a very fast speed.

Some positives:

• Written in C++ and compiled this is the fastest of the tools by far. Especially for the amount of work it does. That being said, we are talking about a difference between seconds and a fraction of a second.
• Can generate documentation in a number of forms not just HTML.
• Supports Markdown and documentation pages. I can write tutorials right within the codebase.
• You can easily see the source from right within the documentation.
• Diagrams with the structure of your code.
• Just so many features.

Some of the pain points:

• My C++ is rusty. If it were written in PHP I’d be much more likely to contribute. The C++ makes is faster but raises the barrier to contributions from PHP devs.
• Customization of the HTML visual output is limited and not super simple.
• The @return tag doesn’t natively accept the returned type. To deal with this for PHP they added @retval. To work with IDEs and introspection you need to implement both of these. In addition \ is seen as an escape character so you needed to replace it with :: in your namespace names within documentation.

Conclusion

Looking over these tools the most important point I’ve learned is that there are several good tools for documentation. If you choose any of these and document your code well it will be a positive. I won’t compare these and declare one a winner.

The one I will be keeping the closest eye on is Sami. While it is the least feature rich of these options (being the newest this is what I expect) it is also in the style of application that I would most like to work in.

But, for the time being my existing projects will continue to use Doxygen. I’m using some features I have not found a way to move away from. Don’t be surprised if I switch in the not to distant future. This revitalized space and interesting options could easily make the happen.