如何使用JSDoc記錄ECMA6類？

Question

背景

我在Nodejs中有一個使用ECMA6類的項目，並且正在使用JSDoc注釋我的代碼，以使其他開發人員可以更輕松地訪問它。

但是，我的評論未被該工具很好地接受，並且我的文檔簡直是火車殘骸。

問題

我的問題是我不知道如何使用JSDoc記錄ECMA6類，而且找不到任何體面的信息。

我嘗試了什么

我嘗試閱讀官方示例，但我發現它缺乏而且不完整。 我的班級有成員，常量變量等等，而且我通常不知道該用什么標簽。

我還在網絡上進行了廣泛的搜索，但是我發現的大多數信息都是在2015年之前的，當時JSDocs還不支持ECMA6腳本。 最近的文章很少，不能滿足我的需求。

我找到的最接近的東西是此GitHub問題：

• 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;

題

給定上面的迷你類示例，您將如何使用JSDoc對其進行記錄？

一個例子將不勝感激。

Answer 1

答案很晚，但是由於遇到了其他問題，我認為我會有所作為。

到目前為止，您可能已經發現JSDoc站點上有關於如何記錄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，因此僅需要指定諸如私有成員之類的屬性。

Answer 2

對於在2019年訪問此問題的任何人：
@FredStark給出的答案仍然是正確的，但是，應注意以下幾點：

1. 此頁面中的大多數/所有鏈接均無效。 有關JSDoc的文檔，請參見此處 。
2. 在許多IDE或代碼編輯器（例如VSCode）中，您會發現自動補全（例如@class或@constructor ，對於ES6類而言，這是不必要的，因為這些編輯器會在new關鍵字之后識別出構造函數。