Theme JSDoc Conventions

• AMD modules
  • What's that pointless define JSDoc which is always ignored?
• Functions
• Properties

JavaScript should be commented with JSDoc 3. This is still a work in progress but new code may not be accepted if it is not appropriately documented. Appropriate documentation is that at a minimum the public members of a module are fully documented.

AMD modules

The return function of the define should be tagged with the @module tag as per JSDoc AMD modules. This is usually done before the define() declaration;

// use this:
/**
 * A module representing a foo control.
 * @module
 */
define([....], function(....) {
    ....
});

// rather than
define([....], function(....) {
  /**
   * A module representing a foo control.
   * @module
   */
  // ....
});

When the module returns a function use the @alias tag.

// use this:
/**
 * A module representing a foo control.
 * @module moduleName
 */
define([....], function(....) {
  /** @alias module:moduleName */
  return function() {
    ....
  };
});

There are some variations on this to make JSDoc3 work with our singleton model. The best approach is to take a look at a similar module. One common variation, for example, is for a module which returns a function to declare the function and return a reference to that function rather than returning the function directly as the latter has been show to cause JSDoc to fail and there is no significant difference in the final compressed code.

What's that pointless define JSDoc which is always ignored?

You may see that the return function argument of a define has JSDoc for each param followed by @ignore. This is only to make Netbeans behave as we prefer to show warning on incomplete JSDoc. The presence of the module header JSDoc comment makes these @param tags mandatory in Netbeans with this JSDoc rule in place. It is a bit annoying but removes a potential mask of real issues.

Functions

Each function comment should include a brief outline of the purpose of the function. Markdown is acceptable in the function description. If you use HTML in JSDoc then it must be in XHTML format (closing tags are never optional). Each function declaration header comment should contain the @function tag. Arguments must be commented using the @param tag. The function scope should be explicitly declared using @public, @private or @protected.

Mandatory tags in a function header block are:

• @function along with the name if it is an aliased function;
• one of @private, @public, @protected or @ignore (see Making properties and methods public for testing below); and
• @param when the function has arguments.
• A constructor must also include the @constructor tag and an @alias tag if required.

Properties

Class level properties should be commented using @var, @constant etc. The comment should include the type and default value as well as a description of the variable.

@since, @author and @copyright tags are optional. All WComponents core JavaScript IP is in accordance with the WComponents licence making @copyright mostly irrelevant.