How we make API references.
How do we create API documentation for CloudStack?
Engineers include descriptive annotations when they write code. In Java, annotations start with @.
Some of the annotations we have defined to contain documentation strings look like this:
@Implementation(description="Creates an account", responseObject=UserResponse.class)
public class CreateAccountCmd extends BaseCmd {
public static final Logger s_logger = Logger.getLogger(CreateAccountCmd.class.getName());
private static final String s_name = "createaccountresponse";
/////////////////////////////////////////////////////
//////////////// API parameters /////////////////////
/////////////////////////////////////////////////////
@Parameter(name=ApiConstants.ACCOUNT, type=CommandType.STRING,
description="Creates the user under the specified account.")
private String accountName;
See the description=" " inside @Implementation and @Parameter. That text will be extracted in the Java to HTML step.
For more information, see Annotations in the API.
There is one piece of code that converts the Java annotations to XML output. Then there is another piece of code that takes in the XML for the table of contents as well as each command, and generates the HTML documents which we upload to our website.
The API doc building script is located at:
setup/apidoc/build-apidoc.sh
It calls the following to create intermediate XML output:
server/src/com/cloud/api/doc/ApiXmlDocWriter.java
After creating the XML files with ApiXmlDocWriter, the script calls the following:
setup/apidoc/XmlToHtmlConverter.java
This XmlToHtmlConverter uses a series of .xsl transforms (aka style sheets) to convert the XML to HTML. Those .xsl’s are all stored in:
setup/apidoc/*.xsl
There is a "diff.txt" file which is auto-generated. This lists all added, removed, and changed API commands versus the prior point release of CloudStack.