Page 1 of 1

Tools to generate API documentation for PHP code?

Posted: Tue Aug 18, 2009 2:57 pm
by Christopher
I am using phpDocumentor on a project for API documentation. It seems pretty widely used (Zend, etc.) but it is not the simplest thing to use. I have the basics working and have been cleaning up comments to make the docs better. But it seems massive and the documentation created is almost too complicated.

Do people have other API documentation generation tools they like better? Are there people who like phpDocumentor and have made it work well?

Re: Tools to generate API documentation for PHP code?

Posted: Wed Aug 19, 2009 3:26 pm
by alex.barylski
I use both phpDocumentor and Doxygen...the latter is a little easier to install and configure in my opinion but both generate about the same documentation.

Re: Tools to generate API documentation for PHP code?

Posted: Wed Aug 19, 2009 10:01 pm
by Ollie Saunders
I really don't like PHPDoc; the docblocks are ugly, the documentation takes ages to generate, the error messages are bad when it goes wrong, there's a ton of mark-up to learn, and the value of the documentation is generates is questionable when compared to just browsing the actual source.

The most useful aspect about documentation for me is the additional, conceptual, information about functions and classes, examples, and tutorials that you don't want to appear in the source coupled with the important bits from the source. Otherwise you might as well be reading the source code with all the blocks folded in by your editor. So I wrote a documentation tool for Fluidics oriented around producing that sort of documentation. All it really does is scrape code out of source files and let you dump them in any kind of document you like (I did it in Markdown but you could do it any mark-up language or plain text you like). Comments are associated with functions/classes/interfaces by being placed directly above them written with // syntax (# is reserved for that you wish not to include in the scrape) and with files by appearing immediately after <?php again in // syntax.

I wrote it in a couple of days it's pretty hacky but I hope it's interesting to you, at least as an idea if not in implementation.

A tutorial template using the scraper
The code being scraped
Resultant HTML produced after template and Markdown evaluation
Hakcy scraper implementation
Script to generate the docs for my project.
make would probably be a better choice if your familar with that.

Re: Tools to generate API documentation for PHP code?

Posted: Thu Aug 20, 2009 1:37 am
by Christopher
Thanks Ollie. I will give it a try. You don't happen to have a all the files in a zip file by chance? ;)

Also, does your code use the PHP reflection library which provide both information about the code and access to comment blocks?

Re: Tools to generate API documentation for PHP code?

Posted: Thu Aug 20, 2009 7:37 am
by Ollie Saunders
It's done with get_token_all(), some searching and, forward and backward iteration over that. If you find the scraper doesn't do everything you'd quite like it to or doesn't handle the edge cases you need it to (because I suspect it probably won't) feel free to contribute back any improvements you make. I couldn't use reflection because that only works for ugly /** */ syntax.

I've put a tar.gz and zip for the 0.4.1 version up on the download page for you.

Re: Tools to generate API documentation for PHP code?

Posted: Thu Aug 20, 2009 10:45 am
by Christopher
Thanks. I will take a look and, of course, give back any improvements.