In the last few days I've spent some time researching for a documentation tool for my PHP sources, and after running a couple of circles, I've ended up using Doxygen.
It had some issues though, especially referring to namespaces in the docblock comments, because the docblock syntax allows using backslashes for commands, e.g. \param instead of @param.
I really don't understand why PHP's developers decided to use backslashes as separators for namespaces, but that's a different story.
So, if you use namespaces in docblock comments, you have to escape backslashes, but I didn't want to do that in my code, so I've created an input filter for Doxygen in PHP which does that for me.
It also appends variable names to @var type declarations, so e.g.
* @var string
* @var string $name
which would be redundant in your code, but Doxygen seems to prefer this format.
I've added the filter to a Bitbucket repository, find it here:
Licensed under the MIT License.
See the Doxygen documentation on how to use an input filter, but basically it's just adding a line like this to your Doxyfile config file:
INPUT_FILTER = /home/tom/misc-tools/doxygen/filter.php
Comments are welcome.