The JSDoc Summarize2 Plugin

A JSDoc plugin to transform the first of the description tags into a summary tag.

Example
Motivation
Quick start
Usage
How to install
How to uninstall
Version history
Contributing
License

Summarize2 is a plugin for JSDoc, which is a tool to generate HTML documentation from comment blocks added directly in JavaScript source code. A JSDoc comment block looks like this:

/**
 * @summary A short description of a program element.
 *
 * @description A long and more or less detailed description of a program
 * element, usually spanning multiple lines and eventually with HTML and
 * markdown formatted text.
 *
 * @type {string}
 */

The Summarize2 plugin rewrites some tags of the comment block according to a set of simple rules. In short, when there is more than one description tag, the plugin transforms the first one into a summary tag, if it doesn't already exist.

Example

Here is a JSDoc comment block of a simple function.

/**
 * Adds two Fibonacci primes.
 *
 * @param {number} x The first addend.
 * @param {number} y The second addend.
 *
 * @returns {number} The sum of x and y.
 *
 * @description Sums two numbers only if both are Fibonacci primes.
 * Otherwise the function returns -1 to indicate an error.
 *
 * @description A Fibonacci prime is a Fibonacci number that is prime.
 *
 * @see https://en.wikipedia.org/wiki/Fibonacci_prime
 */

When JSDoc runs, Summarize2 changes the original comment block as follows:

• A summary tag is created from the first (untagged) description.
• The two other descriptions are combined into a single one.

/**
 * @summary A function to add two Fibonacci primes.
 *
 * @param {number} first The first number to add.
 * @param {number} second The second number to add.
 *
 * @returns {number} The sum of `first` and `second` numbers.
 *
 * @description Sums two numbers only if both are Fibonacci primes.
 * Otherwise the function returns -1 to indicate an error.<br/>
 * A Fibonacci prime is a Fibonacci number that is prime.
 *
 * @see https://en.wikipedia.org/wiki/Fibonacci_prime
 */

The full example is in the example directory. You can also see the HTML page generated by JSDoc as well as the markdown document generated by jsdoc-to-markdown.

Motivation

The Visual Studio Code Intellisense uses JSDoc tags to determine object types. The absence of the summary tag lets the Intellisense output a little bit cleaner. Also, sometimes it's good to create multiple paragraphs of description without markdown or HTML embedded tags. In essence, it's just a matter of taste.

Consider the following JSDoc comment block with two description tags. The first one is untagged and the second is tagged.

/**
 * A short description of a program element.
 *
 * @description A long and more or less detailed description of a program
 * element, usually spanning multiple lines and eventually with HTML and
 * markdown formatted text.
 *
 * @type {string}
 */

The default behavior of JSDoc is to use only the last description in the comment block. Previous descriptions, if any, are ignored. Using the Summarize2 plugin, you can write a comment block like the one above and, during the JSDoc run, the plugin automatically transforms the first description into a summary.

Quick start

1. Install the npm packages.
2. Create the JSDoc configuration file.
3. Generate the HTML documentation.

The following code samples use path/to/file.js to represent the source code file names.

Unix

npm install --save-dev jsdoc
npm install --save-dev jsdoc-summarize2

cp ./node_modules/jsdoc-summarize2/example/jsdoc-conf.json .

./node_modules/.bin/jsdoc -c jsdoc-conf.json path/to/file.js

Windows

npm install --save-dev jsdoc
npm install --save-dev jsdoc-summarize2

copy .\node_modules\jsdoc-summarize2\example\jsdoc-conf.json .

.\node_modules\.bin\jsdoc -c jsdoc-conf.json path/to/file.js

Usage

Run JSDoc with the --configure or -c command line option to use the configuration file prepared during the installation. The installation instructions suggest the name jsdoc-conf.json for it. The paths of the individual source code files must also be passed as command line arguments.

The following instructions use index.js, module1.js and module2.js as examples of source code file names. Additionally, they use the npx command to run JSDoc. The command npx jsdoc is equivalent to ./node_modules/.bin/jsdoc (with backslash on Windows). npx is available as of npm@5.2.0.

npx jsdoc -c jsdoc-conf.json index.js module1.js module2.js

If you prefer, use the scripts property in the package.json to define a command to execute JSDoc via npm run.

"scripts": {
    "jsdoc": "jsdoc -c jsdoc-conf.json index.js module1.js module2.js"
},

Now you can run JSDoc via npm run with the previously defined arguments.

npm run jsdoc

Transformation rules

These are the rules used by Summarize2 to process the comment blocks. The example directory contains the source code to demonstrate all cases.

• If the comment block already has a summary tag, nothing will change.

• A single description tag will not change.

• If there are two description tags in the comment block, the first one is transformed into a summary.

                    +---------------+
  @description +--> |    summary    |
                    +---------------+
  
                    +---------------+
  @description +--> |  description  |
                    +---------------+
  

• If there are more than two description tags in the comment block, the first one is transformed into a summary and the remaining are combined into a single description.

                    +---------------+
  @description +--> |    summary    |
                    +---------------+
  
                    +---------------+
  @description +--> | description 1 |
        +---------> | description 2 |
        |           +---------------+
        +
  @description
  

How to install

The following instructions install the packages locally. If you prefer a global rather than a local install, please use -g instead of --save-dev.

1. First you need to install JSDoc, if it's not already installed.

   npm install --save-dev jsdoc
   

2. Then you should install Summarize2. The package name is jsdoc-summarize2.

   npm install --save-dev jsdoc-summarize2
   

3. Next you need to tell JSDoc to enable the Summarize2 plugin. You do this by creating a JSDoc configuration file with the appropriate parameters. When you later run JSDoc, you must tell it to use the prepared configuration file.

   The plugins property in the JSDoc configuration file must include a Summarize2 plugin reference, as follows:

   "plugins": [
       "jsdoc-summarize2"
   ],

   If needed, you can create a JSDoc configuration file from scratch in the target project directory (the project you want to document). The suggested name is jsdoc-conf.json. You can copy the contents from the following example:

   {
       "plugins": [
           "jsdoc-summarize2"
       ],
       "recurseDepth": 10,
       "source": {
           "includePattern": ".+\\.js(doc|x)?$",
           "excludePattern": "(^|\\/|\\\\)_"
       },
       "sourceType": "module",
       "tags": {
           "allowUnknownTags": true,
           "dictionaries": [
               "jsdoc",
               "closure"
           ]
       },
       "templates": {
           "cleverLinks": false,
           "monospaceLinks": false
       }
   }

How to uninstall

The following instructions uninstall the locally installed packages. If you did a global rather than a local install, please use -g instead of --save-dev.

To uninstall Summarize2:

1. Remove the Summarize2 plugin reference from the plugins property in the JSDoc configuration file. The installation instructions suggest the name jsdoc-conf.json for it.

    "plugins": [
   -    "jsdoc-summarize2"
    ],

2. Uninstall Summarize2.

   npm uninstall --save-dev jsdoc-summarize2
   

If you want to uninstall JSDoc also:

1. If you changed the scripts property in the package.json to define a command to execute JSDoc via npm run, then remove that command definition.

    "scripts": {
   -    "jsdoc": "jsdoc -c jsdoc-conf.json index.js module1.js module2.js"
    },

2. Delete the JSDoc configuration file. The installation instructions suggest the name jsdoc-conf.json for it.

   rm jsdoc-conf.json (Unix)
   
   del jsdoc-conf.json (Windows)
   

3. Uninstall JSDoc.

   npm uninstall --save-dev jsdoc
   

Version history

The file NEWS.md provides a high-level summary of the changes in each release. Users are advised to review the change history before switching to a new version of the package.

The file CHANGELOG.md contains a list of changes committed to the source control. Developers can read the commit history to help them when investigating bugs, conceptual inconsistencies and other issues.

Contributing

Your contributions are welcome! Have a look at the contribution guidelines in the file CONTRIBUTING.md.

License

The Summarize2 plugin is free software, licensed under the terms of the MIT License as published by the Open Source Initiative. It is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the file LICENSE for more details. If you don't find it, please see the MIT License template at http://opensource.org/licenses/MIT.

Copyright (C) 2018 Jorge Ramos https://github.com/jramos-br