Tutorial

• Install ESDoc
• Create Config File
• Write Documentation Tags
• Document Coverage
• Integrate Test Codes
• Integrate Manual
• Appendix
  • Target Code Style
  • Target Identifier

This tutorial explains how to generate a document with the following JavaScript source code.

my-project/
├── README.md
├── package.json
└── src
    ├── MyClass.js
    └── MySuperClass.js

my-project/src/MyClass.js

import MySuperClass from './MySuperClass.js';

export default class MyClass extends MySuperClass {
  constructor(name = 'anonymous') {
    super();
    this._name = name;
  }

  sayMyName() {
    return `My name is ${this._name}`;
  }
}

my-project/src/MySuperClass.js

export default class MySuperClass {
  constructor() {
  }

  sayHello(){
    return 'Hello!';
  }
}

my-project/README.md

# My Project
this is My Project README

Install ESDoc

Install ESDoc with npm.

npm install esdoc -g
esdoc -h

Create Config File

Create ESDoc config file.

my-project/esdoc.json

{
  "source": "./src",
  "destination": "./out/esdoc"
}

Execute ESDoc and see output document.

esdoc -c ./esdoc.json
open ./out/esdoc/index.html

This is minimum configuration. You can see full configuration in the Config page.

Write Documentation Tags

The documentation is not good, because it is generated by the source code without tag(e.g. @param). So, write documentation tags.

my-project/src/MyClass.js

import MySuperClass from './MySuperClass.js';

/**
 * this is MyClass description.
 */
export default class MyClass extends MySuperClass {
  /**
   * this is MyClass constructor description.
   * @param {string} [name="anonymous"] - this is name description.
   */
  constructor(name = 'anonymous') {
    super();
    this._name = name;
  }

  /**
   * this is sayMyName description
   * @returns {string} this is return description.
   */
  sayMyName() {
    return `My name is ${this._name}`;
  }
}

my-project/src/SuperMyClass.js

/**
 * this is MySuperClass description.
 */
export default class MySuperClass {
  /**
   * this is MySuperClass constructor description.
   */
  constructor() {
  }

  /**
   * this is sayHello description.
   * @returns {string} this is return description.
   */
  sayHello(){
    return 'Hello!';
  }
}

execute ESDoc and see output document.

esdoc -c ./esdoc.json
open ./out/esdoc/index.html

Congratulation! The document is good!

ESDoc has some tags. Tags page describes full tags. You can see all tags in the Tags page.

Document Coverage

ESDoc measures document coverage.

See my-project/out/esdoc/source.html

If you want to display documentation coverage badge, use badge of ESDoc Hosting Service.

Integrate Test Codes

ESDoc can integrate test codes into documentation. (Now, support only Mocha)

Write test code.

my-project/test/MyClassTest.js

import assert from 'assert';
import MyClass from '../src/MyClass.js';

describe('MyClass is super useful class.', ()=>{
  it('say my name', ()=>{
    let foo = new MyClass('Alice');
    assert.equal(foo.sayMyName(), 'My name is Alice');
  })
});

And add test configuration.

my-project/esdoc.json

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

Execute ESDoc and see output document.

esdoc -c ./esdoc.json
open ./out/esdoc/index.html

Write tags for test code

my-project/test/MyClassTest.js

import assert from 'assert';
import MyClass from '../src/MyClass.js';

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

Integrate Manual

ESDoc can integrate manual into documentation. Write manual that is overview, installation, usage, example, FAQ and changelog.

my-project/manual/overview.md

# Overview
This is my project overview.

## Author
Alice

## License
MIT

And add manual configuration.

{
  "source": "./src",
  "destination": "./out/esdoc",
  "test": {
    "type": "mocha",
    "source": "./test"
  },
  "manual": {
    "overview": "./manual/overview.md",
    "installation": "./manual/installation.md",
    "usage": "./manual/usage.md",
    "tutorial": "./manual/tutorial.md",
    "configuration": "./manual/configuration.md",
    "example": "./manual/example.md",
    "faq": "./manual/faq.md",
    "changelog": "./CHANGELOG.md"
  }
}

You can specify a only part of these manuals (e.g. overview and installation).

Execute ESDoc and see output document.

esdoc -c ./esdoc.json
open ./out/esdoc/index.html

---

Appendix

Target Code Style

ESDoc targets at ES6 class and import/export style.

• Use class, extends, static, constructor, method, get and set syntax.
  • If you want to target at ES5, might better to use JSDoc.
• Use import and export syntax for module.

Target Identifier

ESDoc processes only top level identifier.

// this is processed.
class MyClass {
}

(function(){
  // this is not processed.
  class MyClass{
  }
})();

You can control target identifiers with access, unexportIdentifier and undocumentIdentifier in config file. See Config.

---

Tutorial is finish! Please enjoy writing documentation with ESDoc!