Skip to content

JSDoc Writing Helper

António Afonso edited this page Nov 13, 2013 · 1 revision

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

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>}