如何使用JSDoc记录ECMA6类？

Question

如何使用JSDoc记录ECMA6类？

javascriptnode.jsdocumentationjsdoc

40

背景

我正在使用ECMA6类编写Nodejs项目，并使用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进行文档化？

请提供一个示例。

- Flame_Phoenix

2个回答

7

针对2019年访问此问题的任何人：
@FredStark 给出的答案仍然是正确的，但需要注意以下几点：

此页面中的大部分/全部链接已失效。有关 JSDoc 的文档，请参见此处。
在许多 IDE 或代码编辑器（如 VSCode）中，您可能会发现自动完成功能，例如 @class 或 @constructor，但这些并不适用于 ES6 类，因为这些编辑器将在 new 关键字之后识别构造函数。

- Ramtin

1

感谢更新，@Ramtin。通常这样的更新应该只是作为原回答的编辑添加，所以我已经更新了链接。另外请注意，我在我的回答中已经提到了第二点。 - coagmano

网页内容由stack overflow 提供, 点击上面的

可以查看英文原文，
原文链接

- coagmano · Accepted Answer

晚回答了，但由于我在搜索其他内容时遇到了这个问题，所以我想试着解决一下。

您可能已经发现了 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，所以只有私有成员之类的奇怪情况需要指定。