Meta Documentation

General Documentation

We are using jsdoc for documenting the author library.

Documentation blocks for jsdoc should start with /** and generally follow the javadoc format and markup style:

/**
 * Main function description.
 * @function functionName
 * @return {Object} random variable
 */

The following is a quick reference of useful markup tags.

Documenting Services

All services in Angular should be linked to modules. In jsdoc we tag the service as @module and the module as @namespace (this is confusing, but it seems to work best with the doc output).

Sample

    /**
     * @module globalRegistry
     * @memberof app.core
     * @description
     *
     * The `globalRegistry` constant wraps around RV global registry for a single point of reference. Use this to access `RV` global.
     * It's useful if we need to change the name of the global registry.
     */

Notes

  • @memberof should reference the angular module (@namespace in jsdoc)
  • Markdown can be used within the description section

Documenting Directives

Ideally angular directives would be listed separately from services. Unfortunately all angular specific doc tools seem to break and lack documentation. As such we are using the same structure for modules; however, if it becomes possible to easily separate them in the future we would like to do so.

Sample

    /**
     * @module avShell
     * @memberof app.layout
     * @restrict E
     * @description
     *
     * The `ShellController` controller handles the shell which is the visible part of the layout.
     * `self.isLoading` is initially `true` and causes the loading overlay to be displayed; when `configService` resolves, it's set to `false` and the loading overly is removed.
     */

Notes

  • @restrict is left over from our earlier attempt to document directives, it can remain in place and will be ignored by jsdoc

Documenting Functions

Javascript allows functions to be defined in a variety of ways. In the context of a service or directive the function will automatically be linked as long as the @module tag is declared on the top level item.

Sample

        /**
         * Add RCS config layers to configuration after startup has finished
         * @function rcsAddKeys
         * @param {Array}  keys    list of keys marking which layers to retrieve
         * @return {Promise} promise of full config nodes for newly added layers
         */

Notes

  • @function can be omitted for @class contexts, the parser is smart enough to figure that out, @function should be used everywhere else
  • if documenting a Promise describe the type which it will resolve with (simply knowing that you get back a promise is not very helpful)
  • @private can be used to document functions which are not exposed by the service, directive or class being documented