Having all of this on mind I have been looking for what was available and I have discovered some interesting tools like the following ones:

phpSearchdoc is a component of the enzyme project. Since enzyme is a big project there was the need of documenting it. Their developers have been writing their own documentation system and they have been kind enough to release it also as an independent package. The documentation gets first written into a database and then it can be viewed with some PHP scripts as a dynamic web site.

The idea to separate parsing logic from presentation is indeed good, however phpSearchdoc (version 1.01) doesn't have a real parser but looks for keywords anywhere in the source, even within comments. In fact, it really have happened to me to have the word 'function' within my comments, and yes, the parser got fooled by thinking that the words following this word were the function's name. Unfortunately then, I was unlucky to have an apostrophe (') in the same line, and when I was trying to write data into the database, mysql has complained (the apostrophe is used to delimit strings in mysql).

Furthermore it's really difficoult to set up and get it working since it's still in alpha state. And after all it's more a cross reference generator than a documentation system because, as far as I know, you can't add your own comments to functions or methods.

phpxref, as the name suggests seems to be more oriented to the generation of a cross reference than a real documentation. Further it seems to be suited more for a regular procedural programming rather than for object oriented programming.

phpautodoc aims to be for PHP what Javadoc is for Java. It seemed to be the perfect solution for my documentation needs. To try it out I had to compile the CGI version of PHP (I normally use the module version), because the generator is written in PHP. I could compile and install the static executable on a Linux system easily with these commands:

rm config.cache
make clean
./configure
make
cp php /usr/local/bin