Tools to generate API documentation for PHP code?

Not for 'how-to' coding questions but PHP theory instead, this forum is here for those of us who wish to learn about design aspects of programming with PHP.

Moderator: General Moderators

Post Reply
User avatar
Christopher
Site Administrator
Posts: 13596
Joined: Wed Aug 25, 2004 7:54 pm
Location: New York, NY, US

Tools to generate API documentation for PHP code?

Post 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?
(#10850)
alex.barylski
DevNet Evangelist
Posts: 6267
Joined: Tue Dec 21, 2004 5:00 pm
Location: Winnipeg

Re: Tools to generate API documentation for PHP code?

Post 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.
User avatar
Ollie Saunders
DevNet Master
Posts: 3179
Joined: Tue May 24, 2005 6:01 pm
Location: UK

Re: Tools to generate API documentation for PHP code?

Post 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.
User avatar
Christopher
Site Administrator
Posts: 13596
Joined: Wed Aug 25, 2004 7:54 pm
Location: New York, NY, US

Re: Tools to generate API documentation for PHP code?

Post 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?
(#10850)
User avatar
Ollie Saunders
DevNet Master
Posts: 3179
Joined: Tue May 24, 2005 6:01 pm
Location: UK

Re: Tools to generate API documentation for PHP code?

Post 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.
User avatar
Christopher
Site Administrator
Posts: 13596
Joined: Wed Aug 25, 2004 7:54 pm
Location: New York, NY, US

Re: Tools to generate API documentation for PHP code?

Post by Christopher »

Thanks. I will take a look and, of course, give back any improvements.
(#10850)
Post Reply