Versions Compared

Old Version 7

changes.mady.by.user David Grizzanti

Saved on

compared with

New Version Current

changes.mady.by.user Paul Angus

Saved on

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

How we make API references.

Table of Contents

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

Release Notes

...

The ApiXmlDocReader class will read and generate a text file of the difference between two versions of the API XML documents of Apache CloudStack. It needs access to the Xstream and the ApiXmlDocReader class.

You can call it with the following command:

Code Block
java -cp ~/.m2/repository/com/thoughtworks/xstream/xstream/1.4.10/xstream-1.4.10.jar:/path/to/source/cloudstack/dist/rpmbuild/BUILD/cloudstack-4.12.0-SNAPSHOT/server/target/classes \
com.cloud.api.doc.ApiXmlDocReader -old /path/to/4.11.commands.xml -new /path/to/4.12.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. !!