Esdoc is used. Marking your classes/functions with esdoc is mandatory. Tests are mandatory.
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:
- Difference between @version and @since.
- Esdoc Tags
- Esdoc Tutorial
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@interface- to mark class as interface@implements {MyInterface}- to show that class implements interface
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.
npm run esdoc
Command above will automatically generate and open generated documentation in your browser. It's recommended to execute this command every time you create/update docs for your classes.
IMPORTANT Make sure 127.0.0.1 localhost.firebaseio.test is specified
in your /etc/hosts. Look here
for more info.
npm test