An API Template must include the following:
- Syntax: Syntax (prototype) of API
- Description: Detailed description of the API
- Parameters (input, output): Details of all the input and output parameters along with description of values that can be passed.
- Return Value(s): Details of the values returned by API after execution.
- Synopsis: One line description of the API
- Calling Sequence: The order in which an API must be called
- Usage Scenario: Expected scenarios where the API can be used
- Examples: Most of the programmers makes best use of this place and are expert in copying the examples provided illustrating the use of APIs.
- Related APIs: Information on the APIs that could be related to the API being documented
Class / Object/ Method name: Name of class / object / method associated with API
- Data types: Any special data type declared only for specific API
- Header File: Any header file associated with API
- Parent class: Details of any parent class associated with API
- Exceptions / Error Messages: Any exceptions or errors that a user may encounter while using the API
- Notes/Warnings: Special notes or warnings while using the API
- Associations or dependencies (if any)
- API name [Write API name here]
- Synopsis [Provide brief description of the API]
- Include(s) [Provide name of header files to be included.]
- Library / Libraries [Provide name of associated libraries]
- Syntax / Prototype [Detailed Syntax of API, here example of C++]
- Description [Provide detailed description of the API along with exceptions (if any)]
- Argument(s) [Provide the details of parameters/ arguments]
param1 - param1 description, by default an input parameter
param2 [out] – param2 description, output parameter
param3 [in/out] - param3 description, both input and output parameter
- Return Values
ret1 Description of return value
err1 Description of error (Error is also a return value)
- Calling Sequence - Provide the flow chart or sequence in which the API should be called, mention if there is any dependency.
- Usage Scenario - Provide the usage scenario (details on how to use and when to use this API) of the API and possible error or success conditions and how to tackle those errors.
- See Also / Related APIs
API1 (along with cross reference)