Setup Node project using npm

Create main directory, and setup node project using node package manager

mkdir helpers
cd ./helpers
npm init

After last command node package manager will ask for project configurations. You can skip that by clicking enter. We will update it manually.

Adding .gitignore file

It would be helpful to add git ignore file:

touch .gitignore

Inside of .gitignore file should be the following line of code:

node_modules/

Now lets go there a take a look on structure and initial package.json with .gitignore:

Setup Babel

Now we need to setup Babel. Babel.js is JavaScript transpiler (more details on Babel.js site). We will need it in order to use es6 feature, especially export/import functionality because on time when I'm creating this article ESDoc not supports node export/require.

Insert the following dev dependencies to your package.json and run in project directory npm install using terminal.

"devDependencies": {
  "babel-cli": "6.26.0",
  "babel-core": "6.26.0",
  "babel-preset-env": "1.6.0"
},

Next add Babel configuration file .babelrc:
In terminal

touch .babelrc

Here is the content:

{
  "presets": ["env"]
}

TDD approach

We are going to use TDD approach. It stands for Test-driven development.

From wikipedia:

Test-driven development (TDD) is a software development process that relies on the repetition of a very short development cycle: Requirements are turned into very specific test cases, then the software is improved to pass the new tests, only. This is opposed to software development that allows software to be added that is not proven to meet requirements.

Setup Mocha test framework and Chai assertion library

Now we need some great test framework and as was mentioned previously we are going to use Mocha and also Assertion Library Chai (more details on Mocha and Chai site).

Firstly let’s add new dev dependencies to our package.json:

"devDependencies": {
  ...
  "chai": "3.5.0",
  "mocha": "3.1.2"
},

and run in terminal npm install.

Implement first test for MathHelper utility

Now we are ready to create first tests and try if all is working as expected.

Create src and specs folder in helpers directory
In terminal:

mkdir src && mkdir specs

In specs folder add file with name math-helper.spec.js with following content:

import { assert, expect } from 'chai';
import { MathHelper } from '../src/MathHelper.js';describe('Math Helper Tests', () => {
  it('test add method', () => {
    assert.equal(4, MathHelper.add(2, 2));
  });
});

Here we are importing all needed dependencies and creating first test for MathHelper#add method. But do not rush to run it because for now it's not working. Now we need to create our MathHelper class and implement .add() method inside.

So in src folder add file with name MathHelper.js and paste the following content:

export class MathHelper {
  static add(augend, addend) {
    return augend + addend;
  }
}

In order to run our test we need to add new npm command to scripts object inside of package.json file

"scripts": {
  "test-math-helper": "mocha --compilers js:babel-core/register ./specs/MathHelper.spec.js"
},

and run it in terminal:

npm run test-math-helper

In your terminal you should see one test that was successfully passed.
Now let’s add few more tests:

import { assert, expect } from 'chai';
import { MathHelper } from '../src/MathHelper.js';

describe('Math Helper Tests', () => {
  it('test add method', () => {
    assert.equal(4, MathHelper.add(2, 2));
  }); 
  it('test subtract method', () => {
    assert.equal(2, MathHelper.subtract(4, 2));
  }); 
  it('test divide method', () => {
    assert.equal(2, MathHelper.divide(4, 2));
  }); 
  it('test multiply method', () => {
    assert.equal(4, MathHelper.multiply(2, 2));
  });
});

MathHelper class method Implementation:

export class MathHelper {  
  static add(augend, addend) {
    return augend + addend;
  }  
  static subtract(minuend, subtrahend) {
    return minuend - subtrahend;
  }  
  static divide(dividend, divisor) {
    return dividend / divisor;
  }  
  static multiply(multiplier, multiplicand) {
    return multiplier * multiplicand;
  }
}

And once again run it:

Great, all seems to be good.

Setup ESDoc

Let’s create documentation for our awesome Math library. For that task we will choose a ESDoc documentation generator for JavaScript. (more details on ESDoc site)

Add new dependencies into package.json by running in terminal:

npm install esdoc esdoc-standard-plugin

create esdoc configuration file in root folder:

touch .esdoc.json

and here is the content of .esdoc.json:

{
  "source": "./src",
  "destination": "./docs",
  "plugins": [
    {
      "name": "esdoc-standard-plugin",
      "option": {
        "test": {
          "source": "./specs/",
          "interfaces": [
            "describe",
            "it",
            "context",
            "suite",
            "test"
          ],
          "includes": [
            "(spec|Spec|test|Test)\\.js$"
          ],
          "excludes": [
            "\\.config\\.js$"
          ]
        }
      }
    }
  ]
}

add README.md file:

touch README.md

README.md file content:

# Awesome Math Library

Helps to work with numbers.

paste the following line to .gitignore file (here we excluding docs folder)

docs/

add commands to package.json for generating/displaying documentation:

"scripts": {
  "test-math-helper": "mocha --compilers js:babel-core/register ./specs/MathHelper.spec.js",
  "generate-doc": "./node_modules/.bin/esdoc",
  "show-docs": "open ./docs/index.html"
}

Working on the documentation

But before we will generate docs we need to describe our class with methods:

/**
 * Utility class that helps to work with numbers.
 */
export class MathHelper {    
    /**
     * Adds two numbers.
     * @param {number} augend The first number in an addition.
     * @param {number} addend The second number in an addition.
     * @return {number} Returns the total.
     */
    static add(augend, addend) {
        return augend + addend;
    }    
    /**
     * Subtract two numbers.
     * @param {number} minuend The first number in a subtraction.
     * @param {number} subtrahend The second number in a subtraction.
     * @return {number} Returns the difference.
     */
    static subtract(minuend, subtrahend) {
        return minuend - subtrahend;
    }    
    /**
     * Divide two numbers.
     * @param {number} dividend The first number in a division.
     * @param {number} divisor The second number in a division.
     * @return {number} Returns the quotient.
     */
    static divide(dividend, divisor) {
        return dividend / divisor;
    }    
    /**
     * Multiply two numbers.
     * @param {number} multiplier The first number in a multiplication.
     * @param {number} multiplicand The second number in a multiplication.
     * @return {number} Returns the product.
     */
    static multiply(multiplier, multiplicand) {
        return multiplier * multiplicand;
    }
}

Ok, let’s take a look:

Now let’s create documentation for tests:

import { assert, expect } from 'chai';
import { MathHelper } from '../src/MathHelper.js';

/** @test {MathHelper} */
describe('Math Helper Tests', () => {    
    /** @test {MathHelper#add} */
    it('MathHelper#add test method', () => {
        assert.equal(4, MathHelper.add(2, 2));
    });    
    /** @test {MathHelper#subtract} */
    it('MathHelper#subtract test method', () => {
        assert.equal(2, MathHelper.subtract(4, 2));
    });    
    /** @test {MathHelper#divide} */
    it('MathHelper#divide test method', () => {
        assert.equal(2, MathHelper.divide(4, 2));
    });    
    /** @test {MathHelper#multiply} */
    it('MathHelper#multiply test method', () => {
        assert.equal(4, MathHelper.multiply(2, 2));
    });
});

And that's all we need to do!