Question

背景

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

但是，我的评论并未被该工具广泛接受，我的文档也是火车残骸。

问题

我的问题是我不知道如何用JSDoc记录ECMA6类，我找不到任何体面的信息。

我尝试了什么

我试过阅读the official example，但我发现它缺乏且不完整。我的类有成员，常量变量等等，我通常不知道使用哪些标记。

我也在网上进行了广泛的搜索，但我发现的大多数信息都是在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给出的答案仍然是正确的，但是，应注意以下几点：

此页面中的大多数/所有链接均无效。有关JSDoc的文档，请参见here。
在许多IDE或代码编辑器（例如VSCode）中，您会发现诸如@class或@constructor之类的自动完成功能，对于ES6类而言是不必要的，因为这些编辑器将识别出new关键字之后的构造函数。

如何使用JSDoc记录ECMA6类？

背景

问题

我尝试了什么

目的

问题

2 个答案: