One thing about the official Cappuccino documents you may have noticed is that they aren't really "complete" in the sense of inherited methods.  We've found a rather clunky way to get more complete documentation out of Doxygen which we'll describe here.  It is what was used to generate the documentation at the "Cappuccino API Documentation" link (menu at left).

The Problem

Let's take a look at the Doxygen-generated documentation for a Cappuccino class, say CPRadio.  Now we all know the CPRadio class is the button used in radio groups (mutually exclusive sets of buttons).  It is, of course, derived from CPButton and therefor inherits all the methods of a CPButton.  But you can't tell that from the documentation.  The CPButton class provides a setState method which is quite handy when using radio buttons but setState is not shown in the documentation for CPRadio.  Since it's inherited from CPButton you have to go to its documentation, usually through the source code link (for me anyway).

The Fix

Well, the problem seems to stem from the way Objective-J, or at least the way Doxygen parses it.  Since we're using Doxygen's Objective-C parser for Objective-J code Doxygen expects things to "look" a certain way.  Specifically it looks to header files with the Objective-C @interface tags for class definitions.  Objective-J does away with the interface/implementation split and has only @implementation tags.  That's handy for us coders, but it confuses poor old Doxygen.

So here's the clunky fix:  We generate unneeded header files with @interface class definitions so Doxygen is happy.  Of course we don't want to do it by hand so we've put together a simple Ruby script to do it.  I know, it should have been in Objective-J, but I was in a hurry.  Maybe that'll be another page in the future...

Anyway, the script is a massive 40 lines and is attached to this article (called "make_headers").  It is in no way pretty but it seems to work OK.  Warning: It was developed on a Unix system (actually OS X and Linux) so it would need to be modified for Windows (path separators at least).

After you run the make_headers script you'll have an additional set of header files (*.h) in the Cappuccino source tree.  Throwing Doxygen at it will generate correctly linked pages with all the member functions shown, included inherited methods (check out the "List of all members." link on the API pages).  The nice graphical display of inheritance relationships can also be generated if you have Dot (part of Graphviz) installed.  The Doxygen configuration file used to generate the API documentation on this site is also attached here.

Enjoy...

Attachments:

capp.doxy.zip	[Doxygen configuration file]	17 Kb
make_headers.zip	[Header creation script]	0 Kb