如何使用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表示readonly和default自动.JSDoc将正确地获取导出,类和构造函数,因此只需要指定像私有成员那样的怪异.

Answer 2

对于2019年访问过这个问题的人：
@FredStark给出的答案仍然是正确的，但是，应该注意以下几点：

1. 此页面中的大多数/所有链接都已失效。有关 JSDoc 的文档，您可以参见此处。
2. 在许多 IDE 或代码编辑器（例如 VSCode）中，您会发现自动完成，例如@class或@constructor对于 ES6 类的情况来说不是必需的，因为这些编辑器会识别关键字后面的构造函数new。