How we make API references.

Overview

How do we create API documentation for CloudStack?

1. Java Annotations in API code.
2. Cosmetic touch-ups in doc generation code.
3. Java to HTML using Jenkins.
4. Troubleshooting notes

Annotations

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:

...

The API documentation can be built with Maven using the following commands (should work on 4.1 and above):. The belt-and-braces approach which always work is to build everything:

1.  mvn -Pdeveloper -Dnoredist clean install

However if you've just edited the .xsl files since building you can use:

1. mvn -Pdeveloper -Dnoredist clean install
2. mvn clean install
3. mvn -P developer -pl :cloud-apidoc

Built The built documentation can then be found here: tools/apidoc/target/xmldoc/html

...

You can call it with the following command:

java -cp ~/.m2/repository/com/thoughtworks/xstream/xstream/1.4.310/xstream-1.4.310.jar:/path/to/source/cloudstack/dist/rpmbuild/BUILD/cloudstack-4.212.0-SNAPSHOT/server/target/classes \
com.cloud.api.doc.ApiXmlDocReader -old /path/to/4.011.commands.xml -new /path/to/4.112.commands.xml -d /path/to/diff/

You'll find diff.txt in /path/to/diff/diff.txt which will contain the changes between the two files.

Troubleshooting notes

1. You may have to update "tools/apidoc/gen_toc.py" and update the data structure: "known_categories" in case you add a command that it doesn't know how to categorize.
2. You cannot have empty descriptions in your annotations (like description=""). The XML parser python code will get mad and crash, forcing you to have to run build with -e and then go figure out what broke. Thanks for doing -e and updating this wiki with this tip. !!