So last night I went down the path of connecting phpDocumentor2 (phpDoc) to my code so I can find key elements in the classes and objects without having to search through the code editor. That works fine, but it is often faster for me to have an index of the classes, methods, and properties in a browser window. Even better, by publishing on the public CSA site I know can use Google to search my own docs. That is a nice bonus.
This morning, while researching custom templates, I came across a competing tool that threatened derailment of my phpDoc efforts. I came across comments that phpDoc was inferior, not updated, and had poor documentation. The project had been ignored for a few years. Turns out that much of that has been addressed since the phpDoc efforts have continued once again, though there are still plenty of gaps in the documentation of the phpDocumentor2 tool kit. After a brief run with ApiGen, I am back on the phpDoc trail.
I was a bit apprehensive about ApiGen from the start. Why? The official website for ApiGen seems less polished than the phpDoc site. If they can’t make a great first impression on their website, what are the chances they can create decent HTML docs from my code comments? Turns out I liked the generated HTML better than their website. While phpDoc does have holes in their website presentation as far as features sets, command line options, etc. It is easier to find what I am looking for and seems to have much more documentation online than ApiGen. Maybe ApiGen has more documentation, but if it is not easy to find that doesn’t make me more efficient.
The installation of both products was about the same. Use pear to setup a remote archive, and run pear to install the product. However there was one or two fewer steps in installing phpDoc over ApiGen. The big difference, however, was the facilitators required by ApiGen versus phpDoc. phpDoc required far fewer libraries and add-on packs than ApiGen and produces better results. phpDoc is either utilizing more of my CentOS 6 default PHP libraries or it just needs less in the “other frameworks” department to accomplish a similar goal.
As for the NetBeans integration, they are both fairly similar. Neither option functions very differently from the other. They both need a target output directory set. However, for some reason ApiGen requires you to locate the full path to the executable. phpDoc just automatically worked. Slight advantage: phpDoc.
Generated Site : Weight
This is one place where I think ApiGen wins out. The overall “weight” of the produced site for the code documentation has less stuff to push around to and from the public server. That also means that the stuff the pages have to load when people are viewing the site is less. However I think there is a trade off on quality and possibly mobile-aware presentation. Based on sheer “bits and bytes” to get the page online, ApiGen is lighter.
Generated Site : Quality
While I do like the search feature of ApiGen, I quickly discovered it is not a general “search any word” type of search we all are accustomed to on any site. It is more of a “type a few characters and find a class name” search. At least out of the box that is how it seems to be configured. So while the search feature seemed like a plus, it really isn’t that useful to me. Overall the look and feel plus ease of navigation of the phpDoc generate site works better for me.
Overall, I found phpDoc to be the best option at this point. ApiGen isn’t bad, but today phpDoc edges out ApiGen in the areas that matter most to me.
You can compare the results of my simple Tagalong test here: