How to document ECMA6 classes with JSDoc?

问题:

Background

I have a project in Nodejs using ECMA6 classes and I am using JSDoc to comment my code, as to make it more accessible to other developers.

However, my comments are not well accepted by the tool, and my documentation is a train wreck.

Problem

My problem is that I don't know how to document ECMA6 classes with JSDoc and I can't find any decent information.

What I tried

I tried reading the official example but I find it lacking and incomplete. My classes have members, constant variables and much more, and I don't usually know which tags to use for what.

I also made an extensive search in the web, but most information I found is prior to 2015 where JSDocs didn't support ECMA6 scripts yet. Recent articles are scarce and don't cover my needs.

The closest thing I found was this GitHub Issue:

• https://github.com/jsdoc3/jsdoc/issues/819

But it is outdated by now.

Objective

My main objective is to learn how to document ECMA6 classes in NodeJS with JSDoc.

I have a precise example that I would like to see work properly:

/**
 * @fileOverview What is this file for?
 * @author Who am I?
 * @version 2.0.0
 */

"use strict";

//random requirements. 
//I believe you don't have to document these.
let cheerio = require('cheerio');

//constants to be documented. 
//I usually use the @const, @readonly and @default tags for them
const CONST_1 = "1";
const CONST_2 = 2;

//An example class
class MyClass {

    //the class constructor
    constructor(config) {
        //class members. Should be private. 
        this.member1 = config;
        this.member2 = "bananas";
    }

    //A normal method, public
    methodOne() {
       console.log( methodThree("I like bananas"));
    }

    //Another method. Receives a Fruit object parameter, public
    methodTwo(fruit) {
        return "he likes " + fruit.name;
    }

    //private method
    methodThree(str) {
       return "I think " + str;
    }
}
module.exports = MyClass;

Question

Given this mini class example above, how would you go about documenting it using JSDoc?

An example will be appreciated.

回答1:

Late answer, but since I came across this googling something else I thought I'd have a crack at it.

You've probably found by now that the JSDoc site has decent explanations and examples on how to document ES6 features.

Given that, here's how I would document your example:

/**
 * module description
 * @module MyClass
 */
 //constants to be documented. 
 //I usually use the @const, @readonly and @default tags for them
/** @const {String} [description] */
const CONST_1 = "1";
/** @const {Number} [description] */
const CONST_2 = 2;

//An example class
/** MyClass description */
class MyClass {

    //the class constructor
    /**
     * constructor description
     * @param  {[type]} config [description]
     */
    constructor(config) {
        //class members. Should be private. 
        /** @private */
        this.member1 = config;
        /** @private */
        this.member2 = "bananas";
    }

    //A normal method, public
    /** methodOne description */
    methodOne() {
       console.log( methodThree("I like bananas"));
    }

    //Another method. Receives a Fruit object parameter, public
    /**
     * methodTwo description
     * @param  {Object} fruit      [description]
     * @param  {String} fruit.name [description]
     * @return {String}            [description]
     */
    methodTwo(fruit) {
        return "he likes " + fruit.name;
    }

    //private method
    /**   
     * methodThree description
     * @private
     * @param  {String} str [description]
     * @return {String}     [description]
     */
    methodThree(str) {
       return "I think " + str;
    }
}
module.exports = MyClass;

Note that @const implies readonly and default automatically. JSDoc will pick up the export, the @class and the @constructor correctly, so only the oddities like private members need to be specified.

回答2:

For anyone visiting this question in 2019:
The answer given by @FredStark is still correct, however, the following points should be noted:

1. Most/all of the links in this page are dead. For the documentation of the JSDoc, you can see here.
2. In many IDEs or code editors (such as VSCode), you will find auto-completions such as @class or @constructor which are not necessary for the case of ES6 classes since these editors will recognize the constructor after the new keyword.