...
The CloudStack API reference pages do references do not adequately communicate the details of the APIs. This inadequacy of information seems to have affected the user experience of CloudStack APIs.
The purpose of this document is to suggest methods to improve the CloudStack API reference pagesCloudStack API references. Improved CloudStack API reference pages references that adequately describe APIs help users educate themselves about the purpose and usage of the APIs. This knowledge helps them make appropriate decisions when using CloudStack.
TBD
Version | Updated by | Other Contributers | Date | Comments |
---|---|---|---|---|
1.0 | Rajsekhar Kunnampally | Nitin Kumar Maharana | May 20, 2016 | Created the first draft. |
The new template that is defined for the CloudStack API describes the information that an ideal CloudStack API API reference page should contain. Also, this document describes the technical aspects of generating an improved CloudStack API referencereferences.
The current CloudStack API reference page contains references contain the following information:
...
CloudStack uses Java docs for creating API reference pagesreferences. The developer who create creates an API enters the descriptions for the API reference page in the @ APICommand annotation field in the code. ThenFinally, the API reference pages references are generated from the code.
...
The following are the limitations of the current CloudStack API reference pagesreferences:
...
The CloudStack API references miss many pieces of information that are crucial for ensuring an excellent user experience. The proposed template for the CloudStack API reference in Appendix A helps you understand these additional information to be documented for the CloudStack API reference pagesreferences.
This document does not suggest any major changes to our current approach in for creating/generating API reference pagesreferences. The developers will continue adding content in the @APICommand annotation fields for the API that when they create an API. The template in Appendix A can guide them in determining the information that they need to add to the @APICommand annotation fields.
Also, this document proposes Tech Pubs review of the API reference page before publishing the API references.
...
...
...
The following figure delineates the workflow for the generation of API docs from the code:
...
...