Documentation Checklist

JSDoc Overview

Before you can generate JSDoc output you must install JSDoc. JSDoc is available as an npm module. Install it thusly:

# you may have to use sudo if permissions require it
npm install -g jsdoc@"<=3.3.0"

You should now be able to do the following and get something similar:

# should output something like /usr/local/node/bin/jsdoc
which jsdoc

Documentation Style Guide

• JSDoc comment blocks begin with /** and succeeding lines begin with * aligned with the /:

    /**
    * @class JSDoc.Comment.Style
    */

• @type names should be capitalized: String, Number, Boolean, Date, etc.

• Example values, type names, kind names, method names, property names and other similar items are set off with back ticks, e.g.: `moon.Slider`.

• Double asterisks may be used for emphasis: **falsy** values.

• The first reference to a kind/method/property should be @linked. Substitute link text may be used if desired: The [something]{@link enyo.Control#something} property. Subsequent references should just use back ticks (`something`), unless repeating the @link will improve clarity.

• Event documentation should briefly explain when the event fires (typically beginning with the word "Fires"--e.g., "Fires when...", "Fires while...", "Fires in response to..."). If there is a payload (i.e., properties specified on the event object), each property should be named and described.

• When documenting methods, if a method is easily understood, the description should begin with a verb in the present tense, reflecting the method's action--e.g., "Sets <a>.", "Gets <b>.", "Adds <c>.", "Removes <d>.", etc. However, there are a number of cases in which this rule may be ignored, including the following:

  • If the method is best understood in terms of when it is called. ("Called when <x> happens.")
  • If the method is best understood in terms of an effect it has. ("Calling this will result in <y>.")
  • If you need to present background information before explaining what the method does.

Documentation Checklist

• Ensure documentation text does a hard-wrap at 100 columns.
• Document all events and add the @fires pragma to any methods that fire these events.
• Ensure that events are declared with the full event name, i.e. @event enyo.Scroller#onScroll
• Add the @lends pragma between the opening ( and the opening { of the enyo.kind declaration.
• Add the @lends pragma before the published properties block.
• Ensure that all mixins are documented via the @mixes pragma.
• Ensure that a subkind has its parent kind documented via the @extends pragma. If a kind is not specified, add an explicit kind: 'enyo.Control' and document via @extends.
• Remove the in prefix on parameters where possible.
• Explicitly use the @method pragma for enyo.inherit methods.

Tips

• JSDoc @links cannot be split across lines. This includes the replacement text for a @link.

    * [Some text]{@link
    * moon.Something#something} BAD!

Generating Output

To generate output for a single project, run the JSDoc compiler from the root of the project:

jsdoc -c docs/conf.json

Currently there will be errors indicating that certain tags are unknown (e.g., The @ui tag is not a known tag). There should be no other errors.

To open the generated documentation, open docs/out/index.html. On a Mac:

open docs/out/index.html

Sample Documentation

(function (enyo, scope) {
	/**
	* The parameter [object]{@glossary Object} used when displaying a {@link moon.VideoFeedback} control.
	*
	* @typedef {Object} moon.VideoTransportSlider~FeedbackParameterObject
	* @property {Number} [playbackRate] - The playback rate.
	* @property {Number} [jumpSize] - The jump size.
	* @public
	*/

	/**
	* Fires in response to dragging on the video position knob. No additional information is
	* provided in this event.
	*
	* @event moon.VideoTransportSlider#onSeekStart
	* @type {Object}
	* @public
	*/

	/**
	* Fires when user changes the video position.
	*
	* @event moon.VideoTransportSlider#onSeek
	* @type {Object}
	* @property {Number} value - The position to seek to.
	* @public
	*/

	/**
	* {@link moon.VideoTransportSlider} extends {@link moon.Slider}, adding specialized behavior
	* related to video playback.
	*
	* ```javascript
	* {kind: 'moon.VideoTransportSlider', value: 30}
	* ```
	*
	* The [onSeekStart]{@link moon.VideoTransportSlider#event:onSeekStart} event is fired while
	* the control knob is being dragged, the 
	* [onSeekFinish]{@link moon.VideoTransportSlider#event:onSeekFinish} event is fired when the
	* drag finishes, and the [onSeek]{@link moon.VideoTransportSlider#event:onSeek} event is fired
	* when the position is set by tapping the bar.
	*
	* @class moon.VideoTransportSlider
	* @extends moon.Slider
	* @ui
	* @public
	*/
	enyo.kind(
		/** @lends moon.VideoTransportSlider.prototype */ {

		/**
		* @private
		*/
		name: 'moon.VideoTransportSlider',

		/**
		* @private
		*/
		kind: 'moon.Slider',

...
		/**
		* @private
		* @lends moon.VideoTransportSlider.prototype
		*/
		published: {

			/** 
			* Starting point of slider
			*
			* @type {Number}
			* @default 0
			* @public
			*/
			rangeStart: 0,

...

		* Sends current status to [feedback]{@link moon.VideoFeedback} control in response to user 
		* input.
		*
		* @param {String} msg - The string to display.
		* @param {moon.VideoTransportSlider~FeedbackParameterObject} params - A 
		*	[hash]{@glossary Object} of parameters that accompany the message.
		* @param {Boolean} persist - If `true`, the [feedback]{@link moon.VideoFeedback} control will
		*	not be automatically hidden.
		* @param {String} leftSrc - The source url for the image that is displayed on the left side of
		*	the [feedback]{@link moon.VideoFeedback} control.
		* @param {String} rightSrc - The source url for the image that is displayed on the right side 
		*	of the [feedback]{@link moon.VideoFeedback} control.
		* @public
		*/
		feedback: function(msg, params, persist, leftSrc, rightSrc) {
...
	});

})(enyo, this);

Helpful Greps

Make sure all enyo.inherit calls have @method on them:

grep -rB3 enyo.inherit *

Search for old style event declarations:

grep -r "@property {Object} sender" *
```

Search for improperly capitalized `String`, `Number`, `Boolean`
```
grep -r "{[^} ,;]*\(number\|string\|boolean\).*}" *
```

Search for improperly closed {@link}:
```
grep -r {@[^}]*\) *
grep -r {@[^}]*\] *
```

Search for spaces before * in multi-line comments:
```
grep -r "\t \*" *
```

Search for '#event:' in `@fires` and `@event`:
```
grep -r "@\(fires\|event\).*event" *
```

Fixing-Up Earlier Documentation
---
* `@lends` pragma goes before published block
* `@ui` goes immediately before `@public`
* Remove `event:` from `@event` and `@fires` declarations
* Fix up `@event` declarations to remove boilerplate and document only `event` object.  If event doesn't provide any (new) data, add 'No additional information is provided in this event.' to description.
* Older references to kind names (unlinked) should be formatted with back ticks: \`moon.VideoTransportSlider\` vs. \_moon.VideoTranspotSlider\_

Converting Existing Source to JSDoc
---
* Wrap contents in an IIFE.
* Ensure there is a linebreak before the close of the IIFE.
* Convert double-quotes to single-quotes.
* Ensure there is a single whitespace between _function_ and _(_.