ESDoc

Features

ESDoc has some useful features.

Automatically Features

Optional Features

Other Features

ES2015 Class

ESDoc supports ES2015 Class syntax and targets codes that are written by it.

ES2015 Class syntax makes the clear relation of class, method, member, constructor and inheritance.
This means that ESDoc can generate a document without using a tag for these. In other words, you don't need to write tags for classes.

ESDoc automatically generates the under contents by Class syntax.

Note: ESDoc doesn't support prototype base codes and function base codes.

ES2015 Module

ESDoc supports ES2015 Modules syntax and targets codes that are written by it.
ES2015 Modules syntax is file base. So ESDoc treats as one file = one module.

ESDoc displays a import style in accordance with the export style.

This is useful because you not need to see export style in source code.

And you may as well as use esdoc-importpath-plugin to transform path.

Note: ESDoc doesn't support module/require of Node.js.

Built-in Search Documentation

ESDoc supports built-in searching in document with only JavaScript(without server implementation).

The implementation of searching:

Note: This implementation is very naive. There might be a problem in search performance. For now, no problem in 500 indexes.

Guess Type of Variables

ESDoc guesses type of variables using codes if those have no @param.

The following variables are supported.

Note: This implementation is very simple. So ESDoc guesses only primitive values(number, boolean, string).

Documentation Coverage

ESDoc measures a documentation coverage. This is useful information for the following.

ESDoc processes only top-level class, function and variable.
This is based on, ESDoc measures coverage by how much the document is being written out of all the processing target.
And, ESDoc is also to measure coverage of each module, you will have become easier to also find a missing of the document.

For example, this is coverage of ESDoc itself.

If you want to disable coverage, you need to specify false at configuration.

{
  "source": "./path/to/src",
  "destination": "./path/to/esdoc",
  "coverage": false
}

Documentation Lint

If documentation is invalid, ESDoc shows warning log.

export default class Foo {
  /**
   * @param {number} x
   */
  method(p){}
}

If you want to disable this lint, you need to specify false at configuration.

{
  "source": "./path/to/src",
  "destination": "./path/to/esdoc",
  "lint": false
}

Note: For now, ESDoc lints only method/function signature.

Integration Test Codes

Test codes are important information.
So, ESDoc generates a cross reference of test codes and document.

You need to write configurations.

{
  "source": "./src",
  "destination": "./doc",
  "test": {
    "type": "mocha",
    "source": "./test"
  }
}

And write @test tag.

/** @test {MyClass} */
describe('MyClass is super useful class.', ()=>{

  /** @test {MyClass#sayMyName} */
  it('say my name', ()=>{
    let foo = new MyClass('Alice');
    assert.equal(foo.sayMyName(), 'My name is Alice');
  })
});

Note: For now, ESDoc supports only Mocha style(describe/it).

Integration Manual

You can integrate a manual of a your project into documentation. The manual is:

You need to write configurations. All configurations are here.

{
  "source": "./src",
  "destination": "./doc",
  "manual": {
    "overview": ["./manual/overview.md"],
    "usage": ["./manual/usage.md"],
    "example": ["./manual/example.md"]
  }
}

And write manual file using markdown.

# Overview
This is my project overview.
...

Note: ESDoc doesn't support free-style manual sections.

If you want to use asset(image) for manual, you can specify asset directory path.

{
  "source": "./src",
  "destination": "./doc",
  "manual": {
    "asset": "./manual/asset",
    "overview": ["./manual/overview.md"],
    "usage": ["./manual/usage.md"],
    "example": ["./manual/example.md"]
  }
}

If you want to write index of manual, you can specify index file path.

{
  "source": "./src",
  "destination": "./doc",
  "manual": {
    "index": "./manual/index.md",
    "asset": "./manual/asset",
    "overview": ["./manual/overview.md"],
    "usage": ["./manual/usage.md"],
    "example": ["./manual/example.md"]
  }
}

If you want to use manual as documentation index, you can specify global index.

{
  "source": "./src",
  "destination": "./doc",
  "manual": {
    "globalIndex": true,
    "index": "./manual/index.md",
    "asset": "./manual/asset",
    "overview": ["./manual/overview.md"],
    "usage": ["./manual/usage.md"],
    "example": ["./manual/example.md"]
  }
}

ECMAScript Proposal

ESDoc supports a part of ECMAScript Proposal that are implemented by Babel.

If you want to use this, you need to specify experimentalProposal at configuration.
All configurations are here.

{
  "source": "./src",
  "destination": "./doc",
  "experimentalProposal": {
    "classProperties": true,
    "objectRestSpread": true
  }
}


/**
 * this is Foo class.
 */
export default class Foo {
  /**
   * this is static p.
   * @type {number}
   */
  static p = 123;

  /**
   * this is p.
   * @type {number}
   */
  p = 123;

  /**
  * this is method.
  * @param {Object} config - this is config.
  * @param {number} config.x - this is number x.
  * @param {string} config.y - this is string y.
  * @param {number[]} config.a - thi is number[] a.
  * @param {string[]} config.b - thi is number[] b.
  */
  method({x, y, ...z}){}
}

Customize Documentation

If you want to customize a document, you can includes your stylesheets and scripts to the document.
And, ESDoc supports plugin feature. Please read API for more information.

ESDoc Hosting Service

ESDoc Hosting Service generates your documentation via GitHub and hosts it.