Question

ESDoc provides a lot of features.

Doc Comment and Tag

ESDoc obtains a comment called doc comment from a source code.
Then ESDoc generates a document from a tag in a doc comment.

A doc comment is block comment beginning with *. A tag is a text of the form @tagName.

/**
 * This is Foo.
 */
export default class Foo {
  /**
   * @param {number} p - this is p.
   */
  method(p){}
}

ES Class

ESDoc supports ES class syntax and targets codes that are written by it.

ES 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.

• Super classes
• Direct Subclasses and Indirect Subclasses.
• Inherited methods and members from super class.
• Override methods and members from super class.

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

ES Module

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

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

• If export default class Foo{}, displays import Foo from './Foo.js' in Foo class documentation.
• If export class Foo{}, displays import {Foo} from './Foo.js'in Foo class documentation.

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 commonjs.

Plugin Architecture

ESDoc adopts plugin architecture. So, almost all features are provided as plugins.

Especially esdoc-standard-plugin is a packaging plugin with major plugins.
Normally we recommend using this plugin. There are various plugins in esdoc/esdoc-plugins.

You can easily make plugins, and there are many third party plugins.
Please click here for how to make plugins.

Publish HTML

ESDoc generates HTML documents that are easy to see and plain looks.

Documentation Coverage

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

• This leads the motivation of documentation.
• This inspects a missing of documentation.

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.

Documentation Lint

If documentation is invalid, ESDoc shows warning log.

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

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.

/** @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');
  })
});

Integration Manual

You can integrate a manual of a your project into documentation.

# Overview
This is my project overview.
...

Search Documentation

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

The implementation of searching:

• ESDoc made the index(JSON) at the time of document generation.
• The user search from the index.

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

Type Inference

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

The following variables are supported.

• A class type using class syntax.
• A method/function arguments type using default argument syntax.
• A property type using assignment value.
• A return type using return value.

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