Documentation of Zowe comes in various forms depending on the subject being detailed.
Categories
Server Core
Principles of operation and end-user guides (configuration, troubleshooting) should be documented on the wiki. Code documentation follows language-specific formats.
Server Security
Principles of operation and end-user guides (configuration, troubleshooting) should be documented on the wiki. Code documentation follows language-specific formats.
Microservices
Microservices implement a web API, and therefore must be documented for understanding and testing. These web APIs must be accompanied with documentation in the Swagger (https://swagger.io/) format. These documents must be Swagger 2.0, .yaml extension files. ZLUX plugins implementing microservices should store these files within the /doc/swagger folder.
Web Apps
ZLUX Apps should include documentation that explains how to use them, such that this documentation can integrate with a ZLUX documentation reader. This is not strictly API documentation, but rather user guides. The preferred documentation format is a .md extension file that exists in the /doc/guide folder of an App.
Web Framework
Principles of operation and end-user guides (configuration, troubleshooting) should be documented on the wiki. Code documentation follows language-specific formats.
CLI Plugins
CLI Framework
Principles of operation and end-user guides (configuration, troubleshooting) should be documented on the wiki. Code documentation follows language-specific formats.
Languages
Each of the common languages in Zowe have code-documentation-generation tools, each with their own in-code comment style requirements to adhere to in order to generate nice, readable API references. Objects and functions of interest should be commented in accordance to the language-specific tools to result in output that serves as the first point of documentation for APIs.
Typescript
When writing typescript code, comment objects and functions in compliance with JSDoc (http://usejsdoc.org/). If you are writing in an area of the codebase that does not yet have a definition file for jsdoc, be sure to define a configuration file that can be used for future documentation of that code.
Java
When writing typescript code, comment objects and functions in the Javadoc format.
C
When writing C code, comment functions and structs in compliance with Doxygen (www.doxygen.org).