08.Document generation(JSDoc)
- Overview
- Getting started
- Frequently used tags
- How to write JSDoc
- Example
- How to export document
- Ouput result
- Further study
- Reference
Overview
This chapter describes general commenting in controller and logic for generating document that uses JSDoc3.
Why JSDoc?
In Eclipse, auto code complete can be displayed while typing,
detailed list of class names and types can be displayed in outline based on JSDoc written in source code.
Besides, using JSDoc, you can also generate API document in HTML format.
Therefore, code would become tidier, coding process and maintenance would become much more comfortable.
Getting started
Configuring Eclipse
- For English version:
- Window -> Preferences -> JavaScript -> Validator -> JSDoc -> enable "Process JSDoc comments" option
- Creating development project:
Create a development project using JavaScript:- Create new JavaScript project:
- New -> Others -> JavaScript -> JavaScript project
- Convert existing project to a JavaScript project:
- Right click project -> Configure -> Convert to JavaScript project
- Create new JavaScript project:
How to automatically insert memberOf tag
Follow these steps for @memberOf <namespace> to be automatically added after typing /** */.
- Project context menu -> Property -> JavaScript -> Code style -> open Code templates.
（Right click project icon in project explorer to open context menu ) - Click Enable project specific settings
- Choose Import
- Browse to XML code template, then click OK.
※ (right click ⇒ save as)
Note: without using @memberOf, information will not be displayed to outline.
Frequently used tags
| @memberOf <namespace> or <class name> | Specify which namespace or class the defined object belongs to. |
| @name <property name> | Define a property name. Unless specified, name defined for object in the code will be treated as @name. If being specified by @memberOf, this will be assigned to that member. |
| @namespace | Define a namespace. Treated as a member unless specified. |
| @param {type name} argument name | Define type and name of argument. |
| @type <type name> | Define variable type. |
| @returns {type name} comment | Define detailed description of return value. |
| @class | Define a class. |
| @instance | Define an instance method. Unless specified, method will become static (you can still define a static method using @static). |
How to write JSDoc
- Controller:
- Use @class, @name xxxController and @memberOf in object itself.
- Use @memberOf for property. You can also use @type, @param and @returns etc. where necessary.
- Logic:
- Use @class @name xxxLogic and @memberOf in object itself.
- Use @memberOf for property. You can also use @type, @param and @returns etc. where necessary.
Example
(function() {
/**
* Sample controller
*
* @class
* @name SampleController
* @memberOf sample.controller
*/
var sampleController = {
/**
* Controller name (mandatory)
*
* @instance
* @memberOf sample.controller.SampleController
* @type String
*/
__name: 'sample.controller.SampleController'
};
h5.core.expose(sampleController);
})();
(function() {
/**
* Sample logic
*
* @class
* @name SampleLogic
* @memberOf sample.logic
*/
var sampleLogic = {
/**
* Logic name (mandatory)
*
* @instance
* @memberOf sample.logic.SampleLogic
* @type String
*/
__name: 'sample.logic.SampleLogic',
/**
* メソッド
*
* @instance
* @memberOf sample.logic.SampleLogic
* @param {Number} numeric value
* @returns {Number} the double of the numeric value
*/
method: function(num) {
return num * 2;
}
};
h5.core.expose(sampleLogic);
})();
In this example, SampleControllerand SampleLogicuse @memberOf to specify sample.controller and sample.logic, respectively. sample.controller and sample.logic are namespaces, similar to package name in Java. Namespace must be defined in the file to be generated, as below:
* @namespace sample
*/
/**
* @namespace sample.controller
*/
/**
* @namespace sample.logic
*/
Note: If you do not define sample, you cannot define sample.xxx namespace.
How to export document
Follow these steps to export document:
- Download JSDoc module from github:jsdoc.
- Unzip the zip file into appropriate location (this example assumes the file is unzipped to folder named jsdoc under C drive).
- Open command prompt, navigate to C:\jsdoc.
- Execute the following commands to export JSDoc:
java -jar lib/js.jar -modules node_modules -modules rhino_modules ./jsdoc.js [Directory path where JS file to be exported is being stored]
Example: if JS file is stored in C:\src.
java -jar lib/js.jar -modules node_modules -modules rhino_modules ./jsdoc.js C:\src
Besides, you can specified output directory to store exported file using -d or -destination option.
java -jar lib/js.jar -modules node_modules -modules rhino_modules ./jsdoc.js [Directory path where JS file to be exported is being stored] -d [Output directory path]
Example: if a JS file is stored in C:\src and output directory set to C:\dist:
java -jar lib/js.jar -modules node_modules -modules rhino_modules ./jsdoc.js C:\src -d C:\dist
In case output folder is not specified, document will be exported to "out" folder, which will automatically be created in the same folder with jsdoc.js (in this example: C:\jsdoc).
Other options
| オプション | 説明 |
|---|---|
| -t or --template <value> | The name of the template to use. Default: the "default" template |
| -c or --configure <value> | The path to the configuration file. Default: jsdoc dirname + /conf.json |
| -e or --encoding <value> | Assume this encoding when reading all source files. Default: utf-8 |
| -q or --query <value> | Provide a querystring to define custom variable names/values to add to the options hash. |
| -T or --test | Run all tests and quit. |
| -d or --destination <value> | The path to the output folder. Use "console" to dump data to the console. Default: console |
| -p or --private | Display symbols marked with the @private tag. Default: false. |
| -r or --recurse | Recurse into subdirectories when scanning for source code files. |
| -h or --help | Print this message and quit. |
| -X or --explain | Dump all found doclet internals to console and quit. |
If a document is not correctly exported
1. Is the path correctly specified?
2. Do all comments start with /**?
Particularly, using only / will make JSDoc unable to recognize the comments.
Remember to start document comments with /**, or insert a space character such as /** **.
Ouput result
Document generation in hifive
Refer to the link below for hifive API documents generated using JSDoc.
- hifive API documents (only in Japanese now)
Further study
This section describe about working with JSDoc using javascript editor in eclipse WST (part of WTP):
Auto code complete
- Information about the argument can be documented using "@param {type name} argument name".
- Variable type can be defined using "@typeof type name".
Displaying to outline
In eclipse, navigate to:
Window -> Preferences -> JavaScript -> Validator -> JSDoc
Enable "Process JSDoc comments" option. @memberOf will be referred to and displayed to outline.
Type searching (not related to JSDoc)
You can search for type in javascript using "Ctrl + Shift + T" combination.
Reference
Next Chapter⇒Sample Video Searching application