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.