javascript - 如何使用 JSDoc 记录 ECMA6 类？

Question

背景

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

但是，我的评论并没有被该工具很好地接受，我的文档也成了废墟。

问题

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

我尝试了什么

我尝试阅读 the official example但我发现它缺乏和不完整。我的类有成员、常量变量等等，我通常不知道哪些标签用于什么。

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

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

• 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，因此只需要指定像私有(private)成员这样的奇怪内容。