Re: What is API (Applic. Prog. Interface) documentation ?

[Chris Hamilton <chamilton -at- GR -dot- COM>]

@ wrote:
>
>   What is the definition of and examples of what would be included in
> API (Application Program Interface) documentation?

Van--

Here's what we included in the API function and method descriptions for
our current product:

-- function/method signature
-- description
-- dependencies
-- return value
-- parameters
-- related/functions and methods
-- reference to the related user's guide section
-- code sample

The signature is a model of what the function or method looks like. For
instance:

int getInt(String parmName)

is the signature for a Java method called getInt. The method returns an
integer and takes a String parameter called _parmName_. The model would
be different, depending on the language. This is rather tedious to write
and to read all the way through, but it's intended to be used as a
reference.

It's not all that hard to write (unless you've got to read the code and
figure out what it does). I had the benefit of working off specs that
described the methods and functions before they were created. Even if
you do/can read the code, it's probably not a bad idea to confer with
your developers on the code samples, if you can.

Chris
--
Chris Hamilton, Sr. Technical Writer   chamilton -at- gr -dot- com
Greenbrier & Russel                    http://www.gr.com
-------------------------
These views are mine, not my employer's.