Blog Posts

phpdoc compilers and the @inheritDoc

In the PHP content repository, we have a set of interfaces and implementation classes of those interfaces. The interfaces define the standard and are extensively documented. The implementation was built by copying the interfaces and implementing the methods. Now we have the documentation comments duplicated, which is a pain to maintain if we clarify or change anything in the interfaces documentation. If this would be Java, we can rely on the documentation to inherit the main text, @param, @return and @throws from from both parent classes and implemented interfaces. Additionally, its possible to use the {@inheritDoc} annotation to add more text to the main text.

In PHP, there is a couple of doc compilers. While they basically all follow the same syntax as Java uses, none of them gets everything right unfortunately. I tried out three four five six different compilers (table last updated september 14th, 2011 - please check the linked issues to know if they have been fixed since):

Product Issues Namespace Inheritance info inherit doc {@inheritDoc}
PhpDoctor 12 Yes Implemented interfaces not shown: #43 No: #38 Buggy: #35
DocBlox 52 Yes

Yes, since 0.13

Yes Yes
PhpDoc 64 and more No Yes No Not for interfaces: #5306
Doxygen 1.7.4 (PHP mode) 1300 Yes Yes Yes Yes
PHPDox 1 Yes (but no folding in tree) Inherited methods not shown No No
ApiGen 7 Yes Yes Yes Yes

So none of the documentation tools i found is really suitable for the documentation of code that implements an interface. For PHPCR, we are using the PhpDoctor and i like the layout (looks very similar to the good old javadoc output). But for Jackalope, it looks like i should use DocBlox and tell people to not forget to click on the parent class links to see all methods, and hope for the issue to be fixed sometimes. But maybe there are better ideas around?


Note that doxygen does not claim to fully support PHP. I read through the enourmous configuration file to activate the right settings but some of them seem to be ignored. I assume doxygen would support more if you where using it with C or C++.

About the author


Find more about him on Twitter, Google+ and his personal site.

Comments [33]

Mike van Riel, 26.07.2011 10:21 CET

Thank you for mentioning DocBlox in your listing, I am glad you like it.

Concerning Issue #74: it is planned for release 0.13.0, which is to be released in the weekend of the 6th and 7th of August.

Additionally I would like to mention as a note that the DocBlox issue tracker not only contains bugs but we maintain our project's progress in the issue tracker.

According to the issue tracker we have 6 confirmed bugs and over 40 feature requests including long-term wishes.

david, 26.07.2011 10:29 CET

hi mike,
looking forward to 0.13.0 then!
regarding the issue tracker, all projects have bugs and feature requests in their trackers, so its not an overly unfair comparison. however, attractivity of the project also means more feature requests i guess...
i could have included the commit activity, which would very clearly show that docblox is very active, whereas PhpDoctor is a bit inactive for a project that young. PhpDocumentor and doxygen are the dinosaurs and activity on both seems to have pretty much stalled.

Tyrael, 26.07.2011 10:47 CET

thanks for sharing.
could you try https://github.com/theseer/phpdox and add it to the comparison?

Tyrael

PEM, 26.07.2011 11:22 CET

I'd be very interested in seeing this list updated with the latest infos.
It's a very good post and quite informative !
Also the idea of mentioning commit activity is great ! Looking forward to reading news here :)

Thank you for posting !

Patrick Allaert, 26.07.2011 14:22 CET

It should be noted that Doxygen is able to copy documentation from another source thanks to the @copydoc tag.

david, 26.07.2011 15:14 CET

@Tyrael: thanks for the tip. i checked it out and theseer was amazingly fast in fixing an issue i spotted. however, phpdox seems not to support doc inheritance at all (neither implicit nor the {@inheritDoc} and the generated output is less user friendly than with the other compilers.

@patrick: thanks, this is nice but when the inheritance is clear from the code, it seems like a lot of work to manually write the @copydoc annotation for every method. it would be nice if the config switch INHERIT_DOCS = YES would work in php. or did i fail to understand the meaning of that one?


i don't want to spoil the fun, but i seriously wonder why there are so many efforts at building a new php doc compiler (phpdoctor, docblox, phpdox). i can see why people would not want to struggle with the probably old codebase of phpdocumentor or with non-php code in doxygen, but do we really need 3 different from-the-scratch projects?

Mike van Riel, 26.07.2011 15:21 CET

From DocBlox' point of view:

When the project started there was only phpDoctor and phpDocumentor2 as new projects and both used the Reflection classes of PHP. The Reflection classes load everything into memory and the project on which I am working has thus many files that they were (most probably) unable to process this application (TBH: I did not try after phpDocumentor and my other experiences with Reflection).

This, and several other considerations, made me decide to start development on DocBlox (which uses Static Reflection to interpret the source).

phpDox did not exist when I started work on DocBlox.

Tyrael, 26.07.2011 15:25 CET

david thanks for looking into that.
personally I didn't used yet (I found DocBlox before hearing about phpdox and was pleased with it), but Sebastian Bergmann promoted phpdox, and it was reported to be perform even better than DocBlox at that time:
http://www.mail-archive.com/internals@lists.php.net/msg50428.html
could you also add the execution time and peak/avg memory usage for each participant?

having three different nextgen documentation could seem weird, they was started in parallel, and without hype, so at that time, it was easy to miss them.

currently it seems that DocBlox got the biggest traction, but I would write off phpdox yet, because it is backed up/developed by some really smart people.

Tyrael

Patrick Allaert, 26.07.2011 15:51 CET

@david No, INHERIT_DOCS works perfectly in doxygen on PHP projects, at least in version 1.7.4. If it doesn't with your project, then that is a bug you should submit.
If you omit documentation at all from a class, documentation from both parent classes and interfaces are used. @copydoc is used to reuse documentation made elsewhere while adding some specific stuff for example, no need to use it as a replacement of INHERIT_DOCS.

Andrew, 26.07.2011 15:57 CET

Hi David! Thanks for an interesting article (I knew only two of compilers you've tested).
I was wondering if you could try one more :) Our ApiGen: https://github.com/apigen/apigen
It is far from being perfect but its quite powerful and flexible considering its age :)
Thanks.

david, 26.07.2011 16:38 CET

@patrick: wow. ok, i was wrong thinking doxygen is not active. i was using 1.7.1 which was released june 2010 and did not show interfaces and not inherit doc from interfaces. version 1.7.4 indeed inherits correctly and draws nice inheritance + implements graphs.

the only worry i still have is that there seems to be no navigation by namespaces. the namespace tab seems to be broken. there is no list of classes when clicking on a namespace but a mix of doc comments from files in that namespace.

@andrew: thanks, i will give apigen a try tomorrow and add the results here.

Dave S, 26.07.2011 17:21 CET

Interesting stuff, thanks. I have to say I would not touch DocBlox with a bargepole having seen the utter mess it has made of the Zend Framework API docs. Bring back PHPDocumentor!

Mike van Riel, 26.07.2011 17:29 CET

@Dave S, Sorry to hear you feel that way. If you have time, please contact me directly.
I'd like to know what it is that you feel it is an utter mess so I can improve it.
You can find my contact information at the website or at Github.

Tyrael, 26.07.2011 17:58 CET

@Mike I would be surprised if he would have anything other than it is different than phpdoc...
AFAIK there were some bugs which was discovered after ZF changed to DocBlox, but you fixed everything that was reported.
thanks for your hard work!

Tyrael

Arne Blankerts, 27.07.2011 09:00 CET

Hi,

thanks for adding phpDox to the list of tools.

Benjamin just did open a ticket regarding @inheritdoc bringing this blogpost to my attention.

That said, let me add some information regarding the state of phpDox:

- the HTML Output template as of now is a simply proof-of-concept I spent roughly 30-45 minutes on creating as an in-conference hack to demo. It has a lot of shortcomings for now - like no internal links and such. The output layer would be the place though where @inheritdoc would need to be supported. And yes, this is the next big thing i want to do. ;)

- The collector (parsing process) does support any annotation in at least a generic way, enabling the generator process and its builders to do whatever it wants with it. So again, the builder would need to resolve it.

- Due to the dynamic nature of PHP it is not possible to have a reliably working resolution of inherited methods: If a class extends an PHP internal class or other third party code for example there would be nothing in terms of DocBlocks that can be found, if the extension/code providing the classes is not installed on the maschine creating the documentation there is not even an API visible to phpDox. I do realize that is an issue but for now i have not really an idea on how to solve that.

Arne Blankerts, 27.07.2011 09:11 CET

@Tyrael

It may look like we're going to have multiple options to generate API documentation for PHP and i personally like the idea of having a choice.

That said, all projects at least as far as I can tell have either different approaches on it - which may proof the key factor for their survival or distinction - as well as different goals.

As far as I do understand it for instance docblox tries to be a (simple?) replacement for phpDocumentor. My project - phpDox - tries to be something else though: Having it generate a nice html output is merely a bonus that probably will be one of the main use cases for endusers but the codebase as well as all its concepts are more in the direction of a framework allowing lots of different QA tools to work on the intermediate xml format.

phpDox also does not exactly care about any documentation standards or tries to mimick them. PhpDox simply supports any type of annotation that follows the basic syntax rules of DocBlocks.

With that approach any project can add its own annotation logic to their codebase and by providing templates that handle those have them generated in documentation or whatever else they might want to generate from it.

This concept was actually one of the reasons why - when we spoke - Mike and I decided to keep going on each of our own projects - while still every once in a while checkout the codebase of the other :)

Mike van Riel, 27.07.2011 09:21 CET

@Arne, I do not fully agree with your statement. What I agree with is that diversity breeds, or drives, innovation and as such is not necessarily a bad thing.

Concerning application goals I am afraid that I have to disagree.

DocBlox provides three levels of API: commandline, using PHP classes or the intermediate XML format.
As I understand this differs little to none from your own approach.

Concerning being able to process any tag / annotation as long as it adheres to the basic syntax for Docblocks and being able to build upon that / extend it; I can only say that both projects support that approach.

Arne Blankerts, 27.07.2011 09:58 CET

@mvriel:

Despite not mentioning it in writing I didn't say docBlox doesn't support arbitrary annotations. From what I read and so far saw it didn't seem to be your main focus though whereas phpDox' focuses on exactly that.

We obviously have a common ground on how we handle things: reflection and use of an intermediate xml. But as we agreed upon before, this is were our similarities end.

While some differences are merely a matter of taste (one global xml file as in docblox, many xml files in phpDox (one per source file)) or implementation details (tagnames or xml structure), the way how things can get extended and/or are currently implemented differ a lot.

Again, not saying this is good or bad. It's just the way things are and people should choose which way they prefer.

david, 27.07.2011 11:18 CET

@Andrew: i tried out apigen and really like it. added it to the table above.

interesting discussion we get here. i won't take a position pro or contra a specific tool, and note that i am at this point only interested in generating a nice doc with a tool that "works for me", and less with extendability or other future potential of some of the solutions :-)

Initially, this was just about finding a tool for documenting my project. But with the amount of feedback we have here, i am tempted to do a real comparison of the tools... What should be the metrics? I can think of:

* number of issues fixed since 1.1.2010
* number of commits since 1.1.2010
* number of contributors (from version control system)
* build the Jackalope documentation to have a real world example, spot issues
* time to build first time
* time to update/rebuild with just one change
* key concepts - what makes this project unique?

what other things would make sense to compare? this is less about finding "the best" but to help people find their way in the large number of tools available.

Patrick Allaert, 27.07.2011 11:42 CET

@David I think you mentioned many metrics which would duplicate the purpose of Ohloh.net, why not providing a link to their ohloh respective page and/or maybe something like: http://www.ohloh.net/p/compare?project_0=Doxygen&project_1=PHPdox&project_2=DocBlox

Arne Blankerts, 27.07.2011 12:12 CET

@david

As much as i like the idea of comparing tools - and as much as i do understand the basic needs of an enduser ;) of such tool - the metrics of how many people develop or how much changed over time does not give much value - imho.

phpDox for example is a lightweight tool that uses a lot of existing components , Manuel's staticReflection for starters. Since docblox implements its own staticReflection it obviously has more code as well as more potential problems to deal with.

Still the full software is equally complex but the metrics based on the project alone would lie in that regard.


@Patrick Allaert

Ohloh doesn't know ***** about phpDox ;) And i so far didn't see the point in registering every OS software I create at a trillion services and websites that have no obvious benefit for me. I don't even have any idea as to why ohloh believes phpDox is hosted at sf.net ;)

kukulich, 27.07.2011 13:15 CET

Patrick Allaert, 27.07.2011 14:34 CET

@Arne Blankerts maybe choosing "phpDox" was a bad idea considering that an existing (sourceforge) project existed with than name since 2002: http://phpdox.sourceforge.net/ #fail ;-)

I'm all with you regarding registering a software in thousands services, this is why I stick to one: Ohloh ;-)

@David then again, not seeing correctly namespaces' content looks like a local issue, works perfectly here: http://users.telenet.be/patrick_allaert/tmp/doxygen-snapshot.png

david, 27.07.2011 17:27 CET

regarding comparison: indeed, ohloh does a good job of that, better than i could have done. and number of commits and lines of code is not the best metric anyways.

but the really interesting parts to compare are:
* what can the tools do?
* how well and fast do they operate?
* what makes them unique?

i still wonder if we need that many different tools for basically the same task...

david, 27.07.2011 17:29 CET

@patrick: right, seems i have some issue with the namespaces in doxygen. can it be that the feature is only fixed in trunk? i got the 1.7.4 from debian...

Patrick Allaert, 28.07.2011 05:58 CET

@David No, trunk is === to 1.7.4 at the moment. Send me your Doxyfile through mail, I will take a look at it to see if everything is optimized for PHP.

Wil Moore III, 29.07.2011 11:30 CET

I agree with those asking why more start-from-scratch projects. I almost started writing yet another which would have ended up in the static reflection camp as the "everything loaded into memory" was a pain point I wanted to eliminate.

The export to XML was another thing on my todo list.

After due diligence, I realized that Doxygen does everything I need it to do, including the export of XML.

Lukas, 03.08.2011 20:05 CET

First up its great that so many developers are looking into improving documentation generation in the php world. I also agree that it makes sense to explore different approaches (like Reflection vs Intermediate XML mentioned above). So yes driving innovation via choice is great.

But you also have to acknowledge that its kinda crazy that there are now this many tools for the job. This dilutes the resources of the community and adds the burden on users to figure out which tool is the right tool for the job, which seems to require accepting that some features are missing at least for now (bringing us back to the diluting resources argument).

Its clear that neither of the new projects was really aware of the other one when they started. And while there may be smaller differences in approach and priorities aside from the fact that everyone gets attached to their baby (for good reason no less) and their ways of running a project. But I think taking a step back now and then to look at whats going on around you in the same space and being able to compromise to consolidate is part of the "duty" of a good "open source citizen".

Choice is not good if choice is just a euphemism for redundancy.

Lukas, 03.08.2011 20:16 CET

As I just clarified via a tweet on the topic, consolidation can also be in identifying common logic and moving this out to a common library so that each project can continue to work on its unique aspects while working together on the redundant pieces.

Tyrael, 03.08.2011 20:20 CET

@Lukas: the FLOSS always ment redundancy, as it is about the freedom of choice.
if I don't like your project I patch/fork it and change it as I like(and what the license allows me to).

I really don't mind that after years without proper docgen tools, now we have more than one.

Tyrael

Lukas, 03.08.2011 20:25 CET

I disagree. Actually I would argue quite the opposite. FOSS is about reducing redundancy that is breed by the proprietary world. This choice is always good argument is an excuse that hurts the FOSS community. That being said of course everybody is free to do whatever they want, but saying that you can only do good by releasing open source code is not true. Of course this doesnt make the authors evil or anything.

kukulich, 02.09.2011 15:13 CET

The ApiGen issue #35 mentioned in the table has been fixed in the 2.0.3 a couple of weeks ago.

david, 14.09.2011 09:30 CET

thanks. i updated the table and added a note that the table might be outdated and people should check the linked issues.

regarding that follow-up post, i have to much on my plate right now, but will eventually do something again...

Add a comment

Your email adress will never be published. Comment spam will be deleted!