Re:Help required - Using tools for API documentation

Subject: Re:Help required - Using tools for API documentation
From: Chris Grigg <chris -at- grigg -dot- org>
To: "TECHWR-L" <techwr-l -at- lists -dot- raycomm -dot- com>
Date: Tue, 15 Apr 2003 17:17:17 -0700

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)
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

Subject: Help required - Using tools for API documentation
From: "Paresh, Naik (IE10)" <Paresh -dot- Naik -at- honeywell -dot- com>
Date: Mon, 14 Apr 2003 17:44:26 +0530

Dear members,

Has anybody out there tried auto-generating API or SDK documentation?

Apart from general advice on this, I am specifically looking for answers to
the following questions-

* Many commercial tools like TLB2HTML etc. take the output files of
the solution like TLBs , dlls and so on as inputs to the documentation tool.
* Many of the APIs that I need to document are C++ and not COM based -
therefore no typelib is available. How to take care of this? * Typelibraries include all the interfaces they depend on. Therefore,
most of the document generated is for interfaces that are provided by Microsoft.
Is there any smart way to limit the output to the interfaces contained in
the typelibrary?
* Is there a way to add descriptions, in the IDL source code, for
methods and parameters? Looking at MSDN help it appears that this is
for methods (using the 'helpstring' attribute) but how about adding
descriptions for parameters?
* The method of Tools > Build Comment Web Pages in MS VisualStudio
.NET appears to be one way out. However the .NET help says Visual C++
provides limited support for XML documentation comments and C# fully
supports it.
* Does anyone know; what they mean by 'limited 'support?
* What's the smart way to import thousands of interlinked HTML pages,
generated this way, in RoboHTML to generate .chm file?
The File > Import > HTML files option in RoboHTML does not
allow more that 60-70 pages to be imported at a time.
* Apart from Doxygen , which other tools take source (and not output)
files as input?
* Has anyone tried Document!X? It appears it works well for VB.NET,
any reports of it with C++?

Thanks in advance,

Purchase RoboHelp X3 in April and receive a $100 mail-in rebate, plus FREE RoboScreenCapture and WebHelp Merge Module. Order here:

Help celebrate TECHWR-L's 10th Anniversary starting this month!
Check out the contests at
Happy birthday to you, happy birthday to you, happy birthday TECHWR-L....

You are currently subscribed to techwr-l as:
archive -at- raycomm -dot- com
To unsubscribe send a blank email to leave-techwr-l-obscured -at- lists -dot- raycomm -dot- com
Send administrative questions to ejray -at- raycomm -dot- com -dot- Visit for more resources and info.

Previous by Author: Re: Help required - Using tools for API documentation
Next by Author: Re: Tech writer/ Documentation Specialist
Previous by Thread: Re: Help required - Using tools for API documentation
Next by Thread: Levels of Edit: how are they defined/applied by technical editors?

What this post helpful? Share it with friends and colleagues:

Sponsored Ads