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.

Join the Conversation

1 Comment

  1. Is it possible to install phd on PHP 5.2.10… ? if so how ? i dont want to switch to PHP 5.3.x …

    Like

Leave a comment

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out /  Change )

Google photo

You are commenting using your Google account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s

%d bloggers like this: