phpdoc hell

I’ve been fighting with phpdoc for about a week now, trying to figure out how to document my extension, which is a combination of PHP and C code. I finally figured it out, and since I haven’t seen this documented anywhere, I figured I’d reproduce the steps here:

Download phpdoc from CVS.  No!  Not PEAR, you fool!  CVS!  For some reason, the package you download with PEAR and the package you get from CVS are completely different. Luckily, PHP has some instructions on how to download the package with CVS.

For my lovely Javadoc-style PHP-code comments, phpdoc can be used to convert them to XML:

$ phpdoc -d path/to/php/srcs -t output -o XML:DocBook/peardoc2:default

Cool!  Now you have your PHP documentation converted. Now for the C code. CVS phpdoc (and only this phpdoc, not PEAR phpdoc) has a script in scripts/docgen called docgen.php.  You use this as follows:

$ php docgen.php --output tmp --extension extname

That gives you an outline to fill in for you C documentation.  Now you just need to mush them together and generate the manual, to see what it looks like.  This is where I got stuck.  Here’s what I figured out: in phpdoc/manual.xml.in, add 1 line:

&reference.mongo.book;

…except replace “mongo” with whatever your extension’s name is.

Put your xml documentation in the directory phpdoc/en/reference/mongo. In phpdoc/en/reference/ add a file called entities.mongo.xml, and use the other entities files as your guide for its contents.

To actually generate the documentation, go to phpdoc/ and run:

$ php configure.php --with-partial=book.mongo
$ phd -d /path/to/phpdoc/.manual.book.mongo.xml

Et voila.  Point your browser to file:///path/to/phpdoc/html/ref.mongo.html and you can see your documentation.