README.md

Introduction

JSDoc provides an @example for introducing sample code into document annotations.

For example, when you write a piece of code and add a document comment:

/**
 * Book class, representing a book.
 * @constructor
 * @param {string} title - title of the book.
 * @param {string} author - author of books.
 */
Var Book = function (title, author) {
    This. title = title;
    This. author = author;
}

At this point, if you want to add a sample code to the document comment, it might be like this:

/**
 * Book class, representing a book.
 * @constructor
 * @param {string} title - title of the book.
 * @param {string} author - author of books.
 * @example var testBook = new Book ('testbook','hia');
 */
Var Book = function (title, author) {
    This. title = title;
    This. author = author;
}

As shown in the figure, the display block of the corresponding sample code is generated by the identifier @example.

Usage Steps

If that is all your need, then JSDoc itself has achieved your goal. But in many cases, our project itself already contains a lot of code that meets the requirements and can be used as examples in documents. So, for this situation, the best way is to refer to it directly. Unfortunately, JSDoc itself does not provide such identifiers or functions, so the plugin jsdoc-plugin-hia came into being. Here's how to use this plugin to reference the existing code.

1. First, make sure that you have installed JSDoc into your project.
2. Then NPM installs jsdoc-plugin-hia and docdash-hia (themes used to for jsdoc-plugin-hia).

   npm i -D docdash-hia
   npm i -D jsdoc-plugin-hia

3. Make relevant configuration in your JSDoc configuration file (assuming jsdoc-conf.json)

   "plugins": [
       "plugins/markdown",
       "./jsdoc-plugin-hia"
   ],
   "markdown": {
       "hardwrap": true,
       "idInHeadings":true,
       "tags": ["file","overview","property","todo"]
   },
   "opts": {
       "template": "./node_modules/docdash-hia"
   },

4. Find the code block you need to introduce and wrap it with the @codeblock identifier

   /**@codeblock 2018-11-19 18:32:33*/
   var testBook = new Book('testbook', 'hia');
   /**@codeblockend 2018-11-19 18:32:33*/

   The @codeblock is followed by the identifier name, which is recommended: standard naming (combination of letters and numbers), timestamp
5. Use @coderef at the document comment where you want to ref code

       /**
        * Book class, representing a book.
        * @constructor
        * @param {string} title - title of the book.
        * @param {string} author - author of books.
        * @example@coderef 2018-11-19 18:32:33
        */
       Var Book = function (title, author) {
           This. title = title;
           This. author = author;
       }

6. Project root directory execution

   jsdoc ./ -c ./jsdoc-conf.json

   

As shown in the figure, @coderef generates a display block of the corresponding existing code. (Source links to the existing code are also generated)

The above example is short and may not be very convincing, but imagine that if you need to refer to a large piece of code, it's very convenient to use @coderef, especially when you update those codes, you don't need to adjust it in the document commentary second time anymore.

Notes

Coderef can be used in the following identifier blocks:

• @desc
• @example
• @property

In addition, the @coderef function of jsdoc-plugin-hia is cross-file. You can define the codeblock in document A.js and reference it in the document annotation of another file B.js, as long as the identifier name of the codeblock is globally unique, and both A.js and B.js are in the same jsdoc generation cycle.

For further explanation of @coderef, see @coderef