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):

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