JSDoc

JSDoc is a industry standar to document the code of the Javascript project. We can find JSDoc documentation in a lot of OSS and commercial projects.

We encourage the documentation of the modules, as we aim to code in a reusable way. This is important, as we need to document the code in a way that anyone (even ourselves in a couple of months) can understand what was the purpose of the module and all the exposed logic

Example of JSDod documentation

/**
 * @module path/to/file
 * @description
   #My Module
   Markdown is valid here!
 * /

/**
 * @function sum
 * @description Sums two parameters
 * @example
    // js code
    sum(4,5); // returns 9
 * @param {number} a First number
 * @param {number} b Second number
 * @return {number} Sum of the number
export default const sum = (a, b) => {
    return a+b;
    }
 }

How to document

We can assume that we are going to documment, at least:

• Module with the description. This helps to organize the JSDoc exports
• Anything that we exports. This helps us to get the description of the exports when we are coding

One important thing is that we can write markdown text in almost any description. This allow us to selfcontain the module and exports descriptions in a rich way within the code, keeping it in sync to any possible change without the need of updating multiple files.

This becomes critical when we talk about functions/methods definitions.

Is really easy to modify one function and forget to update the associated documentation if we do not enforce it. Thanks to ESLint we can enfoce that the signature of the functions match the description, throwing errors in the opposite way.

JSDoc output

In order to get the render version of the documentation we can run the npm run doc:jsdoc script. This will process all our code (from src/services atm that this document was written) and get the HTML version of the documentation. In order to modify the input folder or the output one we need to modify the script or the jsdoc.js config file on the root of the project.

jsdoc.js example:

'use strict';

module.exports = {
  opts: {
    package: './package.json',
    destination: './docs/jsdoc'
  },
  plugins: ['plugins/markdown'],
  markdown: {
    // tags: ['examples']
  }
};