Re: Documenting a C++ API

Subject: Re: Documenting a C++ API
From: "Camp, Mary" <campm -at- DIALOGIC -dot- COM>
Date: Thu, 21 Sep 1995 15:49:59 -0400

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
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
Description -- more details on the fields, parameters, when to call this,
Cautions -- what happens when you call this, what you should do before
known gotchas, etc.
Example -- code example. Programmers who use it say this is the MOST
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
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

Previous by Author: Data Usage
Next by Author: Re: Set [preposition]?
Previous by Thread: Documenting a C++ API
Next by Thread: Re: Documenting a C++ API

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

Sponsored Ads