API style guides (SUMMARY)

[Lani Hardage <lhardage -at- RMTECH -dot- COM>]

The question: are there any style guides for documenting APIs? I already
looked at several APIs, but they seemed to differ enormously in format.


Responses: you guys were great! I'll summarize briefly in the interest
of bandwidth:

from Walter Hanig: see what your developers think would be useful, and
they will probably use the examples first and more than anything else in
the API descriptions.

from Kathleen Pilopivich: I took much of the info from the headers in
the functions.  I worked with the software developers to include the
other  information they wanted included.

from Darilyn Page: I worked closely with my developers. Each one had
something in particular they liked about a certain API, and some  things
they didn't. Gradually we developed a format that everyone was  happy
with.

from Sara Schertz: I didn't find any standard styles out there --
instead, I worked with a programmer to come up with some standards we
thought would work. We used the function references for Visual Basic and
C++ as a guide, and sort of mixed and matched the styles together until
we came up with something we both liked.

The key was getting programmer input. every programmer I interviewed
agreed that there is no need for a 500 page function reference -- they
would rather have it online with searching available.  consistency is
very important. Every topic in our reference has the exact same layout.
The online guide was STRICTLY a function reference -- it did not tell
you how to program, but instead simply gave the details about each and
every function in the API. We did not include significant code examples
in the reference. Any such examples WOULD (probably) have to be
programming language specific. Instead, one of our developers created a
set of small sample programs (in Visual Basic) that highlight various
functions.      I am now currently finishing up a Developer's Guide for
the same API, which DOES tell you how to program -- we found that the
reference alone is just not enough. In this case, we have many code
examples.

from Chris Hamilton: The same format should suit most languages. Each
function or method should have: signature, description, return value,
parameters, related functions and methods, then your code sample....If a
function or method is overloaded, list all its implementations together
in the signatures section.  The description should include when and why
you would use it and the code sample should include just enough
information to show context. The sample doesn't have to be an entire
function or method.

from Martha Davidson: Check out good ol' UNIX man pages

from David Locke: The only thing that causes problems is the
organization of the diverse content. Organize the information
alphabetically... Inheritance lattices, in which ancestor functionality
is recursively invoked, are also hard to comprehend, and are considered
bad practice.

from Jason Huntington: I always look for ways to automate collection and
formatting of information for long API references... helpful when
functions, methods, or variables change and you have to maintain the API
reference...We decided on two online books: (1) The Developer's
Reference included an index to classes, methods, and variables and, for
each class, a complete discussion of the work the class was expected to
do in the system, pictures and diagrams, and an alphabetical listing of
the public methods and variables belonging to the class... (2)The
Developer's Guide was task-oriented...to extend the program or use
advanced features.

from Johan Lont: You'll find some standards for writing API
documentation on Sun's Java homepages
(http://java.sun.com/products/jdk/javadoc/writingdoccomments.html
[Java-oriented, but with some helpful online standards applicable to any
API doc]