如何使用 JSDoc 记录 ECMA6 类？

Question

背景

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

但是，我的意见并没有被该工具很好地接受，而且我的文档也很糟糕。

问题

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

我试过的

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

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

我找到的最接近的是这个 GitHub 问题：

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

但现在已经过时了。

Objective

我的主要 objective 是学习如何使用 JSDoc 在 NodeJS 中记录 ECMA6 classes。

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

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

问题

鉴于上面这个迷你 class 示例，您将如何使用 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的回答还是正确的，但是需要注意以下几点：

Most/all 个链接已失效。 JSDoc的文档可以看here.
在很多IDE或者代码编辑器中（比如VSCode），你会发现auto-completions比如@class或者@constructor，对于ES6 类因为这些编辑器会识别 new 关键字后的构造函数。

如何使用 JSDoc 记录 ECMA6 类？

How to document ECMA6 classes with JSDoc?

javascript

documentation

node.js

jsdoc

背景

问题

我试过的

Objective

问题