Re: Documenting a C++ API

Subject: Re: Documenting a C++ API
From: Geoff Bradbury <bradg -at- INTEXT -dot- CPSG -dot- COM -dot- AU>
Date: Fri, 22 Sep 1995 10:08:45 +1000

At 15:49 21/09/95 -0400, you wrote:
>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?
[snip]
____________________________________________________________
At 9:41 22/09/95, I wrote:

Greetings Kim...

I handle the documentation for the APIs developed by our software engineers.
The APIs are a part of the Software Development Kits we market. Most are in
standard C rather than C++, but the same ideas still apply (with a little
tweaking).

Each SDK comes with a single Programmer's Guide. One and one only
publication. There were times in the not-so-distant past where one product
could have several publications: not a good look and a mongrel to maintain!
The basic structure I use for Programmer's Guides goes like this:

* Preface - introductory blurb, publication conventions, publication
roadmap, technical assistance info, etc.
* Ch 1 - Understanding the API - the conceptual material, examples of
the API in action, etc.
* Ch 2 - Getting Started - system requirements, API file manifest,
installation instructions (we support Windows and various flavours of unix
platforms), general hints and tips on using the API, compiling and linking
hints and tips, details of the example program we supply as part of the SDK.
* Ch 3 - API Function Summary - provides a thumbnail sketch of each
API call, categorized by functionality. For example, output syntax
specification category, initialization category, etc.
* Ch 4 - API Function Reference - similar structure to ch 3, using a
detailed call layout: function type, parameter types and descriptions,
callback function descriptions, return values, comments, code examples.
* Ch 5 onwards - API-specific material. Some APIs require only a
single chapter, others need several to describe functional areas.
* App A - Operating Limits - Just how far you can push this little
puppy...
* App B - Return Values Reference
* Glossary
* Index

Following this structure and associated page layout standard has resulted in
a growing set of publications that explain each API. I'm still going! More work!

Hope this is of some assistance.

...cheers!
__________________________________________________
Geoff Bradbury - Technical Writer for InTEXT Systems
"Makers of extraordinarily fine text storage and retrieval software"

PO Box 310, Deakin West, ACT 2600, Australia
+61 6 283 6804 (voice) +61 6 285 4316 (fax)

My writings reflect my views: not those of InTEXT Systems

"I love deadlines. I like the whooshing sound they make as they fly by."
- Douglas Adams
__________________________________________________


Previous by Author: Re: Portfolio questions (was Resumes and Cre
Next by Author: Re. Reveal codes a flaw?
Previous by Thread: Re: Documenting a C++ API
Next by Thread: Words into Type, 4th edition


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


Sponsored Ads