Re: Documenting a C++ API

["Camp, Mary" <campm -at- DIALOGIC -dot- COM>]

From:    Kim Ferri x710 <kim -at- ASPECTDV -dot- COM>
>Our product includes a C++ API that enables customers to build their own
> applications using the core functionality of our product.
>Has anyone out there documented a similar C++ API?
>Do you have any advice in terms of organization, detail, examples, etc?

We document our product APIs as well, although we're still only using
regular C (no pluses!). Our 'software references' document all the API
function
calls that can be made, basically an encyclopedia format. All the
functions are
in alphabetical order and each has the following sections:
Quick Reference header -- showing inputs, outputs, includes and 3-5 word
descriptions.
Description -- more details on the fields, parameters, when to call this,
etc.
Cautions -- what happens when you call this, what you should do before
calling,
    known gotchas, etc.
Example -- code example. Programmers who use it say this is the MOST
important.
    Best case is to be actual code fragment from a demo program, not just
a one liner.
Errors -- Error codes that can be returned and (sometimes) a few words of
description
See Also -- cross reference to related functions

Depending on the API, there are more chapters (or another whole manual)
on using
the functions to perform certain tasks. If another manual, it's usually
called a
Programmer's Guide which accompanies the Software Reference. (This type
of org
seems status quo from what I've seen of other companies' docs. Anyone?)

If you hear from anyone else, I'd appreciate if you'd send me a copy or
send to the list.

Hope this helps,
Mary Camp     campm -at- dialogic -dot- com
Technical Writer