This page was written to aid students in my COM1101 class, Winter 2001. They are using C++. But the ideas here apply equally well to other languages, especially Java. Written by Prof. Futrelle, Northeastern Univ., 2/4/2001.
For those writing API documentation for the first time, I've assembled a few examples and included some links to notes about APIs as well as a few excerpts from the notes.
The primary thing to keep in mind is that an API is written to tell some user of your codeabout your code, someone who wants to use the variables, functions and/or classes you have written in their own code. In writing your API, you usually assume that they will have no need to know the internals of the facilities you're giving them to use, and indeed may not be allowed to know or may not have access to the internals. They may only have access to already compiled code and no source code.First, a tiny example:
CLASS
Class Dog
Represents an animal.
MEMBER VARIABLES
public String name
The animal's name, example: "Goldie".
MEMBER FUNCTIONS
void bark(int loudness)
Produces audio output of one bark, with level from 0 (silence) to 10 (loudest).
Values < 0 are interpreted as 0 and > 10 are interpreted as 10.
void rollover(int n)
Produces animated output of a dog rolling over n times.
Values < 1 are interpreted as 1 and > 4 are interpreted as 4.
int hungry()
Returns an integer from 0 through 10 indicating how hungry the dog is,
with 0 corresponding to no hunger and 10 to ravenous.
Here are some comments from a piece by Susan Gallagher:
"API documentation is the gateway into the provided code. Its job is to document and explain the ways in which it is possible to make the code do what it's supposed to do. For example, the API documentation for a charting package would need to explain how to pass the data to be charted into the module and how to request that the appropriate chart type be displayed with that specific data plotted. "
And excerpt from a piece by John Darrow who teaches these skills and is writing a book on the subject.
"At bare minimum, you must identify the functions or methods that the programming customer would use. For each, you must identify its name and purpose, provide a description of the information it needs to get its job done (its arguments or parameters), and describe any information it gives back when it has done its job (known as its return type). Much of this information you can get directly from the code, ...."
There are many software tools that can automatically generate API documentation from your source code, especially when you embed the correctly formatted comments in your sources. Here's a list with links from a Python site.
EXTRA CREDIT: If anyone in the class can get DOC++ or a similar tool working for their C++ code and give us information on how to install and use it, that would be great.
And finally, JavaDoc is the most popular documentation tool in use today. Here's a page I prepared for a Java project some of the COM1101 students are working on. It links to my source code examples with specially formatted comments as well as the HTML pages that the are automatically generated by the javadoc tool. The cell phone topic of the project will be pursued in my COM1204 course in the Spring quarter (Object-Oriented Design).