Re:Help required - Using tools for API documentation

[Chris Grigg <chris -at- grigg -dot- org>]

I have done quite a bit of API documentation for some time now.  In 
my experience, you only want to work from binary/object/DLL files 
when reverse-engineering other parties' products.  When doing API 
product documentation you want to work from the source code wherever 
possible because it's much easier to see what the programmers' design 
intention is, since you can see comments, parameter and variable 
names, enum definitions, etc.  For C++ in particular, the API 
interfaces are almost always expressed in source code header files 
(".h files" or ".cpp files") containing class declarations -- it's 
kind of a de facto requirement for classes in C++ -- so that's where 
most C++ API documenters start.

Unfortunately, I don't know of any commercial tools that do a very 
professional job of auto-documenting C++, just tools for converting 
directly to HTML etc. (i.e. doing what JavaDoc does for Java source 
code).  Whereas I need to go to FrameMaker for reasons of house style 
and single-sourcing to PDF/print/HTML.  So last year as an experiment 
on my own time I wrote a Perl script that turns a given set of C++ 
header files into a fully cross-referenced Class Reference in MIF 
format.  It worked really well, and upon first use saved a huge 
amount of time assembling the backbone of a developer reference 
document for a big commercial music/sound API (dozens of classes, 
hundreds of methods).  I've thought about turning this script into a 
product -- or licensing the code -- but have been too booked-up to 
pursue that.

The MIF file starts with a "Methods Reference" header and a TOC of 
all the classes, and then has a separate section for each class. 
Each class section includes a "class <className>" heading, a list of 
inherited classes, a placeholder for an introduction, a TOC of the 
class' method names (including any inherited methods -- those links 
point to the method entry in the inherited class), and an entry for 
every method in the class.  Each method entry has a 
"<className>::<methodName>" heading, the method prototype, a 
placeholder for the method description, and a details table with one 
row each for Params: (w/param names filled-in & descr. placeholder 
for each param), Returns: (with placeholder for return type  descr.), 
Notes: (with placeholder for any needed notes), Switches: (with 
placeholder for descr. of any relevant compile switch options):, and 
See Also: (with placeholder for any needed cross-references).  Each 
element of the layout has its own para format, and char formats are 
used where needed.

So you just:
	1. Get the C++ header files from the programmers
	2. Run the Perl script, generating the MIF file
	3. Open the MIF file in Frame
	4. Import your house styles from your template (you can configure
	    the script with the name of the format to use for each element)
	and
	5. Start typing your descriptions.

I ran out of time to polish the script, otherwise I'd have also had 
it generate index markers for the class and method names, and had it 
read the format names from a file instead of appearing literally in 
the script's Perl source.  Also, one limitation of the approach I 
took is that the structure of the generated document is hard-coded in 
the Perl script; ideally, that would be driven by some sort of 
user-editable file too. I might also look into extracting comments 
from the source code, but am a little skeptical about this approach 
[since a) programmers don't like having to follow special formatting 
rules for their comments; b) some programmers put comments .above. 
things whereas others put comments .below. things, so comments could 
easily get attached to the wrong method; and c) rare is the 
programmer whose writing really belongs in the product documentation].

So... the main point is: it's a bit of work, but it's do-able, and 
maybe the above will give you some ideas on how to proceed.  You just 
have to understand how to parse C++ class declarations, how MIF 
works, how a MIF file is structured, and be able to write simple text 
processing code (both C++ and MIF are just ASCII text, after all). 
Perl makes this pretty easy. (BTW, I spent some time tracking down 
web leads on MIF processing packages written in Perl, but none of 
them quite panned out, so I just wrote that stuff myself.)

Hope this helps,

	-- Chris Grigg