JSDoc Writing Helper

An example of the style to use, from the Repetition

/**
 * @module "montage/ui/repetition.reel"
 */
var Montage = require("montage").Montage;

/**
 * A component that manages copies of its inner template for each value in its
 * content.  The content is managed by a controller.  The repetition will
 * create a {@link RangeController} for the content if you provide a 
 * [content]{@link Repetition#content} property instead of a
 * [contentController]{@link Repetiti   on#contentController}.
 *
 * Ensures that the document contains iterations in the same order as provided
 * by the content controller.
 *
 * The repetition strives to avoid moving iterations on, off, or around on the
 * document, prefering to inject or retract iterations between ones that
 * remain in their respective order, or even just rebind existing iterations 
 * to alternate content instead of injecting and retracting in the same
 * position.
 * @class Repetition
 * @extends Component
 */
exports.Repetition = Component.specialize(/** @lends Repetition */{
    ...instance stuff...
}, /** @lends Repetition */{
    ...constructor stuff...
});

JSDoc syntax

JSDocs content is rendered as markdown text https://github.com/adam-p/markdown-here/wiki/Markdown-Cheatsheet but it is very important to prefix each line with * and keep them to 80 chars a line. Only add @module information at the beginning of the module, there is no need to document the @require so if they exist remove them. Do not use @throws as it’s parsed as @return, write it in the description of the method.

JSDoc tags documentation

http://usejsdoc.org/

Types’ syntax documentation

• http://usejsdoc.org/tags-type.html
• jsdoc_cheat-sheet-v1.pdf

How to refer to a Montage type

Just use the type name with no module reference, e.g.: Converter.

Which properties to document?

Currently we’re going for the properties that are important for someone who just wants to use components from a user point of view. For instance, initWith functions in components should probably have the @private tag in order to avoid to have them in the API docs. For components the most important properties are the ones to be used in the serialization. If a property doesn’t have any documentation then it will not show up in the API docs, there is no need to add a single @private tag if there’s no documentation.

How to generate the docs from code

1. Clone montagejs.org repository: git clone [email protected]:montagejs/montagejs.org.git.
2. Checkout gh-pages branch: git checkout gh-pages.
3. Run the command: _build/jsdoc/jsdoc-link.js.
4. Run the command: jekyll serve once.
5. Then you can uncomment the apps in the jekyll config open the /_config.yml file and uncomment this line exclude: [apps, built-apps, node_modules, packages, ui].
6. From now on you can run jekyll to rebuild automatically jekyll serve --watch.
7. Open in the browser: http://localhost:4000/api/.

Instructions to install jekyll are available in the montagejs.org README.md file.

FAQ

• Q: {@link #propertyName} doesn’t seem to work

  A: Use [propertyName]{@link ObjectType#propertyName} instead.

• Q: What is the recommended way to document array types

  A: {Array.<Component>}