Skip to content

Latest commit

 

History

History
79 lines (56 loc) · 2.75 KB

ESDOC.md

File metadata and controls

79 lines (56 loc) · 2.75 KB

Esdoc

Esdoc is used to generate detailed documentation and measures documentation coverage. It's mandatory to use Esdoc comments in this project.

Format of esdoc

Sample comment:

/**
 * [foo description]
 * @author Roman Pushkin ([email protected])
 * @date 2016-04-24
 * @version [version]
 * @since [since_version_from_package_json]
 * @param {[type]} a [description]
 * @param {[type]} par [description]
 * @return {[type]} [description]
 */
function foo(a, par)

All parameters are required for public functions. It's also highly recommended to write descriptions for private functions.

Parameter Description
@version Function/class version. When you create a file, set it to 1.1. When you edit and delget it, increment minor version, e.g. to 1.2. Increment major version only if you have breaking changes.
@since Version parameter from package.json

Note that @version is not SEMVER. However, @since is SEMVER.

See also:

Along with tags described above, these tags are also highly recommended to use:

  • @example - use to provide API example
  • @see http:// - use to provide a website link
  • @extends {ParentClass} - use to specify parent class
  • {@link OtherClass} - use to link documentation between one class and another

Esdoc editor configuration

(Optional. You may want just to copy and paste documentation blocks from other parts of the project).

dockblockr plugin is used for Atom (this plugin is also available for Sublime Text).

When using dockblockr, there are two essential commands available when you type:

/**

First command is Enter (press right after you typed /**). Second command is Tab. Depending on command you will either generate class/function description, or just a comment. Please note: there is limited support in dockblockr for es6.

Two important settings for docblockr (in Atom: Cmd+Shift+P -> View installed packages -> docblockr -> Settings):

  • Align tags: no
  • Extra tags: just copy the code below changing your name and email:
@author Roman Pushkin (roman.pushkin\@gmail.com), @date {{date}}, @version ${1:[version]}, @since ${1:[since_version_from_package_json]}

See also: Configuration section on dockblockr plugin page.

Generate documentation

npm run esdoc

Command above will automatically generate documentation. open ./esdoc/index.html to open docs in your browser. It's recommended to execute npm run esdoc every time you create/update docs for your classes.