Tutorial (basic learning) » 08.Document generation(JSDoc)

08.Document generation(JSDoc)

Last modified by kashi on 2015/01/30, 12:51


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

How to automatically insert memberOf tag

Follow these steps for @memberOf <namespace> to be automatically added after typing /** */.

  1. Project context menu -> Property -> JavaScript -> Code style -> open Code templates.
    (Right click project icon in project explorer to open context menu )
  2. Click Enable project specific settings
  3. Choose Import
  4. Browse to XML code template, then click OK.

Find out XML code templates here (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.
@namespaceDefine a namespace. Treated as a member unless specified.
@param {type name} argument nameDefine type and name of argument.
@type <type name>Define variable type.
@returns {type name} commentDefine detailed description of return value.
@classDefine a class.
@instanceDefine 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.


(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'

(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;

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 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 --testRun 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 --privateDisplay symbols marked with the @private tag. Default: false.
-r or --recurseRecurse into subdirectories when scanning for source code files.
-h or --helpPrint this message and quit.
-X or --explainDump 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.

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.


Library > JSDoc3

Next Chapter⇒Sample Video Searching application

Copyright (C) 2012-2017 NS Solutions Corporation, All Rights Reserved.