kis-jsdoc-plugin

A JSDoc plugin associated with a custom template that generates markdown documentation in a 'Keep It Simple' way.

Description

• The role of this plugin is to generate a markdown documentation of your project based on JSDoc comments of your code.
• It will auto infer properties like @export, @private, @public, @class for EcmaScript projects with modules and export/import syntax.
• It generates a markdown file for each of your commented source file and a markdown table of contents.
• You can add categories in order to sort your documentation in the table of contents.
• You can add screenshots to documented modules or classes.

Requirements

This plugin is written in EcmaScript 2015 so a version of node.js > to 6.4 is required. It has been developed and tested with the 3.5.5 release of JSDoc.

Installation

Install kis-jsdoc-plugin within you project:

1npm install --save-dev kis-jsdoc-plugin

Create or modify your .jsdoc.json config file to reference the kis-jsdoc-plugin plugin and the markdown custom template:

1{
2  "tags": {
3    "allowUnknownTags": true
4  },
5  "source": {
6    "include": ["./src"] /* the path to your documented source code */
7  },
8  "opts": {
9    "template": "node_modules/kis-jsdoc-plugin/templates/markdown",
10    "encoding": "utf8",
11    "destination": "./doc/", /* the path to the generated documentation */
12    "recurse": true
13  },
14  "plugins": ["node_modules/kis-jsdoc-plugin"],
15  "templates": {
16    "markdown": {
17      "tocfilename": "toc.md" /* the name of the table of contents file */
18    }
19  }
20}

Running

Run JSDoc:

1jsdoc -c ./.jsdoc.json

Coding coventions

• EcmaScript 2015 classes do not need @class tag and if they are using export declaration they do not need @export tag. All their members and methods are then considered public (no need for @public tag) except if they begin with _ (no need for @private tag).

1/**
2 * Defines my EcmaScript2015 class.
3 */
4export class MyClass {
5
6  /** @member {string} - The private member. */
7  _bar;
8  /** @member {string} - The public member. */
9  foo;
10
11  /**
12   * The public method.
13   */
14  foobar() {
15  }
16}

• CommonJS/node modules do require a @module tag and functions or constants with export declaration do not need @public or @export tag. The name of the module is automatically computed based on the file name, but you can indicate yours.

1/**
2 * Defines a JavaScript module.
3 * @module
4 */
5
6/**
7 * Defines a private function.
8 */
9function bar() {
10}
11
12/**
13 * Defines a public function.
14 * @param {number} x - The x parameter.
15 */
16exports.foo = x => ...;

Automatic links to class documentation

If all you EcmaScript classes have unique names and if you use the class name as parameters of your @param, @return, @see tags or {@link} inline tag, a markdown link to the corresponding class documentation will be created.

1/**
2 * Defines a new class using {@link MyClass}.
3 * @see MyClass
4 */
5export class AnotherClass {
6
7/**
8 * Defines a public method.
9 * @param {MyClass} myClass - The instance of the class.
10 */
11bar(myClass) {

You can also add external links to classes in the configuration file like this:

1{
2  "templates": {
3      "externallinks": {
4        "HttpClient": "https://aurelia.io/docs/api/fetch-client/class/HttpClient",
5        "Router": "https://aurelia.io/docs/api/router/class/AppRouter",
6        "Promise": "https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise"
7      }
8   }
9 }

The following comment in your code:

1  /**
2   * Creates an instance of the SettingsService with the specified parameters.
3   * @param {HttpClient} client - the fetch http client
4   */
5  constructor(client) {

will generate this:

Creates an instance of the SettingsService with the specified parameters.

Parameters	Type	Description
client	HttpClient	the fetch http client

Exclude private code

You can opt out the generation of private members or functions with the following configuration:

1{
2  "opts": {
3    "includes": "public"  /* default is "public,protected,private" */
4  },

Modifiers badges

The modifiers like public, private, protected, static, abstract are represented by an svg badge. You can opt out for a png file in case svg does not fit your need. Use this configuration:

1{
2  "templates": {
3    "markdown": {
4      "imageext": "png"  /* default is "svg" */

Category

This plugin register a new @category JSDoc tag. It will be used to generate the table of contents. You can add whatever category you want.

1/**
2 * Implements the user settings.
3 * @category Model
4 */
5export class UserSettings {

You can modify the order of the categories in the table of contents with the following configuration:

1{
2  "templates": {
3    "markdown": {
4      "tocOrder": {
5        "model": 1,
6        "viewmodel": 2
7      }

A badge will be generated for the category and you can define the color with the following configuration:

1{
2  "templates": {
3    "markdown": {
4      "badgecolors": {
5        "model": "009663",
6        "viewmodel": "00A800"
7      }

Table of contents

A table of contents documentation is generated in a separated file. You can change the name in the configuration file:

1{
2  "templates": {
3    "markdown": {
4      "tocfilename": "toc.md"
5    }

Screenshots

For a module or class, you can add a png image to the {your_doc_folder}/images/screenshots folder with the same name as the original source file and the image will be added to the corresponding documentation markdown file.

Customization

You can provide your own handlebars templates for the markdown generation by specifying the folder in the configuration file:

1{
2  "opts": {
3    "template": "{your_template_folder}",  /* the default is node_modules/kis-jsdoc-plugin/templates/markdown */

You need to provide two handlebars files :

• toc.hbs, that will be used for the table of contents
• module.hbs, that will be used for each documented javascript file.

You can also provide handlebars partials in the partials subfolder and they will be precompiled and registered by their filenames.

Note that the doclet object model for each documented javascript has the following hierarchy:

• module
  • constants
  • functions
    • params
    • examples
  • members
    • examples
  • classes
    • classes (the constructors of the class)
      • params
      • examples
    • functions (the methods of the class)
      • params
      • examples
    • members

Using TypeScript to describe type

JSDoc uses its own syntax or Google closures to describe types. Unfortunately it does not really support TypeScript although Visual Studio Code is able to infer type with JSDoc TypeScript definitions. This plugin enables to reconstruct valid documentation from TypeScript definitions even if the JSDoc CLI will complain with following errors:

ERROR: Unable to parse a tag's type expression for source file...

Note that the following comments formats are supported for functions:

1 /**
2  * Function description.
3  * @param {(user: User) => void} p1 parameter description
4  * @return {Promise<{ name: string }>} return description
5  */
6  function f1(p1) { 
7   ...
8  }
9
10or
11
12 /**
13  * Function description.
14  * @param {(user: User) => void} parameter1 parameter description
15  * @return {Promise<{ name: string }>} return description
16  */
17 const f1 = p1 => {
18   ...
19 }

Note that the following comments formats are supported for members:

1 /** @type {() => {name: string}} the member description */ m1;
2
3 /**
4  * the member description
5  * @type {() => {name: string}}
6  */
7 get m1() {
8   ...
9 }

Project documentation

The project documentantion has been self generated by this plugin and the table of contents is available here: Table of contents

Known issues & limitations

Only the following JSDoc tags are currently used in markdown templates: @augments, @class, @constant, @example, @member, @module, @param, @private, @public, @return, @see, @static, @type.