News Archive
PhpRiot Newsletter
Your Email Address:

More information

phpdoc compilers and the @inheritDoc

Note: This article was originally published at Planet PHP on 26 July 2011.
Planet PHP

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 four different compilers:

Product Issues Namespace Inheritance info inherit doc {@inheritDoc} PhpDoctor 12 Yes Implemented interfaces not shown: #43 No:A#38 Buggy: #35 DocBlox 52 Yes Inherited methods not shown: #74 Yes Yes PhpDoc 64 and more No Yes No Not for interfaces: #5306 Doxygen (PHP mode) 1300 Incomplete Implemented interfaces not shown NoA(for PHP) ?

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++.