如何使用 JSDoc 记录 ECMA6 类？

背景

我在 Nodejs 中有一个使用 ECMA6 类的项目，我正在使用JSDoc http://usejsdoc.org/评论我的代码，以便其他开发人员更容易访问它。

然而，我的评论并没有被该工具很好地接受，而且我的文档也很糟糕。

Problem

我的问题是我不知道如何使用 JSDoc 记录 ECMA6 类，并且找不到任何合适的信息。

我尝试过的

我尝试阅读官方例子 http://usejsdoc.org/howto-es2015-classes.html但我发现它缺乏且不完整。我的类有成员、常量变量等等，但我通常不知道使用哪些标签来做什么。

我还在网上进行了广泛的搜索，但我找到的大多数信息都是 2015 年之前的，当时 JSDocs 还不支持 ECMA6 脚本。最近的文章很少，不能满足我的需求。

我发现的最接近的是这个 GitHub Issue：

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

但现在它已经过时了。

客观的

我的主要目标是学习如何使用 JSDoc 在 NodeJS 中记录 ECMA6 类。

我有一个精确的例子，我希望看到它正常工作：

/**
 * @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

鉴于上面的这个迷你类示例，您将如何使用 JSDoc 来记录它？

举个例子将不胜感激。

迟到的答案，但自从我在谷歌搜索其他东西时发现了这个，我想我会破解它。

您现在可能已经发现JSDoc https://jsdoc.app/网站有关于如何记录 ES6 功能的不错的解释和示例。

鉴于此，我将如何记录您的示例：

/**
 * 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;

请注意，@const 意味着只读并自动默认。 JSDoc 将正确选择导出、@class 和 @constructor，因此只需要指定像私有成员这样的奇怪内容。