There are several options available on the market. Among them are
PHPDocumentor http://www.phpdoc.org/
PHPXref http://phpxref.sourceforge.net/
Doxygen http://www.doxygen.org
and others... http://en.wikipedia.org/wiki/Comparison_of_documentation_generators

Nobody is perfect, we need to find the one that suits us the most.

I did some research on Doxygen (the most maintained one among listed above) and this is my resume:
Doxygen creates a very nice looking pages with class hierarchy diagrams, index pages, etc.
It also has some bugs/features:
1. File-level phpdocs are not recognized unless there is a @file token in them. And we don't have this token in moodle. Other generators automatically recognize the first phpdocs block as file-level.
2. define() statement is displayed as enumeration instead of constant (https://bugzilla.gnome.org/show_bug.cgi?id=358976)
3. If variable comment only has one line starting with @var - it is ignored (https://bugzilla.gnome.org/show_bug.cgi?id=626105)
4. html file names are generated in the same directory (or split between random directories), and it is impossible to guess the name of file by the name of class/function

The workarounds:
1-3. pre-process files with some script before feeding them to Doxygen - add @file in first phpdoc, change all define() to const and remove @var when needed
4. we create a script that runs through already generated indexes of files, directories, classes, functions (very easy to parse) and fill the DB table with the mapping.
We developers can insert tokens in dev docs like
[phpdocs:class:core_renderer]
[phpdocs:file:lib/moodlelib.php]
[phpdocs:code:lib/moodlelib.php]
[phpdocs:element:CLASSNAME::ELEMENTNAME]
etc. and there is some script that lookup in our table and converts it into URL
(note, the table also has a version field)