TechWhirl (TECHWR-L) is a resource for technical writing and technical communications professionals of all experience levels and in all industries to share their experiences and acquire information.
For two decades, technical communicators have turned to TechWhirl to ask and answer questions about the always-changing world of technical communications, such as tools, skills, career paths, methodologies, and emerging industries. The TechWhirl Archives and magazine, created for, by and about technical writers, offer a wealth of knowledge to everyone with an interest in any aspect of technical communications.
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
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)
the functions to perform certain tasks. If another manual, it's usually
Programmer's Guide which accompanies the Software Reference. (This type
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