Page 1 of 1

New Improved API Documentation with Doxygen

Posted: Fri Jan 02, 2009 7:48 pm
by ramaboo
I love Swift Mailer and use it in almost every PHP project I create. I just wanted to let the development team know about Doxygen (http://www.doxygen.org) . Its an API documenter much like phpDocument (only I think much better).

I ran the Swift Mailer 3.3.3 though Doxygen and this is the result:
http://ramaboo.com/docs/swiftmailer/html/annotated.html

Compared to the phpDocumentor documentation at http://www.swiftmailer.org/api/php5/index.html I think its a marked improvement.

Doxygen is very easy to use. Once you install it you just create a Doxyfile (download mine using $ wget http://ramaboo.com/docs/swiftmailer/Doxyfile) and place it in the same directory as Swift.php. You will also need to create a header.html ($ wget http://ramaboo.com/docs/swiftmailer/header.html) and footer.html ($ wget http://ramaboo.com/docs/swiftmailer/footer.html)

Then run:
$ doxygen Doxyfile

and it will create the documentation in the html directory.

-David

p.s. I have used Doxygen 1.5.8 to generate the above documentation. This version is a few ahead of what are in most of the repositories out here so if you run 1.5.5 you might get a few warnings which can safely be ignored.

p.p.s. This was run on an unedited version of Swift Mailer. A few small source code changes could make the Doxygen output even better.

Re: New Improved API Documentation with Doxygen

Posted: Fri Jan 02, 2009 11:27 pm
by Chris Corbyn
Thanks for this :)

I'm actually planning on including the API documentation directly in the main documentation (radically different) in version 4 using XSLT. I imagine Doxygen can output in any format you like provided you write the transformations so I should be able to get it to integrate with my DITA documentation as a series of topics in XML.

Re: New Improved API Documentation with Doxygen

Posted: Sat Jan 03, 2009 5:13 am
by ramaboo
Yes it will output XML. There are also several XSLT scripts out there that others have written.