I have been involved in writing some guidelines on how to document API's so that they look uniform across the product. The challenge here is that i am suppose to arrive that for any language through which the SDK exposes the API's (C++, C#) for example. Here is what i arrived at.
They are language and technology agnostic. The techniques that solves them in the respective language shall be described in later sections.
-
The behavior/summary of the API is usually described in more precise manner (1 or 2 lines). (Comment: If you are not able to do that, then the API is doing more than one function :))
-
The details shall be described in a more explanatory manner.
-
Examples are given in the appropriate language.
-
List the versions in which the API is supported
-
State whether the API is thread safe or not.
-
Have links to other relavent topics.
-
Have detailed description on the parameters and return values. For return values state what a return value means.
-
Have detailed description of the exception that will be thrown from the API and why it is thrown.
-
Who are the callers to an API, any events triggered by the API.
-
If there are any specific context where the API's behavior is unobvious.
-
Any conventions, like index starts from 1 for the array, first parameter is dependent on the second
-
If there are paths as parameters/return values, how are they ? are they relative/absolute, other fallback mechanisms
-
Mention if the API can be consumed in automation/COM clients, its behavior thus.
-
Use references to parameters and other types/classes whenever necessary.