如何使用JSDoc记录ECMA6类？ [英] How to document ECMA6 classes with JSDoc?

问题描述

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

I have a project in Nodejs using ECMA6 classes and I am using JSDoc to comment my code, as to make it more accessible to other developers.

但是，我的评论并没有得到工具的认可，我的文档也是火车残骸。

However, my comments are not well accepted by the tool, and my documentation is a train wreck.

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

My problem is that I don't know how to document ECMA6 classes with JSDoc and I can't find any decent information.

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

I tried reading the official example but I find it lacking and incomplete. My classes have members, constant variables and much more, and I don't usually know which tags to use for what.

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

I also made an extensive search in the web, but most information I found is prior to 2015 where JSDocs didn't support ECMA6 scripts yet. Recent articles are scarce and don't cover my needs.

我发现最接近的是这个GitHub问题：

The closest thing I found was this GitHub Issue:

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

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

但它现在已经过时了。

But it is outdated by now.

我的主要目标是学习如何使用JSDoc在NodeJS中记录ECMA6类。

My main objective is to learn how to document ECMA6 classes in NodeJS with JSDoc.

我有一个确切的例子，我希望看到它正常工作：

I have a precise example that I would like to see work properly:

/**
 * @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记录它？

Question

Given this mini class example above, how would you go about documenting it using JSDoc?

一个例子将不胜感激。

推荐答案

迟到的答案，但是因为我偶然发现了谷歌上的其他东西，我以为我会对它有所了解。

Late answer, but since I came across this googling something else I thought I'd have a crack at it.

你可能现在发现 JSDoc 网站有关于如何记录ES6功能的不错解释和示例。

You've probably found by now that the JSDoc site has decent explanations and examples on how to document ES6 features.

鉴于此，我将记录您的示例：

Given that, here's how I would document your example:

/**
 * 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将正确地获取导出，类和构造函数，因此只需要指定像私有成员那样的怪异。

Note that @const implies readonly and default automatically. JSDoc will pick up the export, the class and the constructor correctly, so only the oddities like private members need to be specified.

这篇关于如何使用JSDoc记录ECMA6类？的文章就介绍到这了，希望我们推荐的答案对大家有所帮助，也希望大家多多支持IT屋！