phpdoc compilers and the @inheritDoc

26.7.2011

I repost some of my blog posts made @ liip. Please see here for the original post and comments: http://blog.liip.ch/archive/2011/07/26/phpdoc-compilers-and-inheritdoc.html



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

testing php