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 and other similar items are set off with back ticks: `moon.Slider`.
• Double asterisks can be used for emphasis: **falsy** values.
• The first reference to another kind, method, property should be @linked. A substitute can be used if desired: The [`something`]{@link enyo.Control#something} property. Other references should just use back ticks over the substitute, unless @linking improves clarity.

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 @ui is an unknown 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
	*/

	/**
	* `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,

...

		* Send 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\).*}" *
```

Fixing-Up Earlier Documentation
---
* `@lends` pragma goes before published block
* `@ui` goes 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 _(_.