JSDoc可以记录动态生成的方法吗? [英] Can JSDoc document dynamically generated methods?

问题描述

这是构造函数 A ，它为实例提供2种方法: printThing 和 printBall .我使用 JSDoc 来记录这样的方法:

Here is a constructor function A that gives instances 2 methods: printThing and printBall. I use JSDoc to document methods like this:

var A = function () {

    /**
     * Prints 'Thing'
     * @param {Number} N - The number of times to print.
     */
    this.printThing = function (N) {
        var i = 0;
        while (i < N) {
            console.log('Thing');
            i++
        }
    };

    /**
     * Prints 'Ball'
     * @param {Number} N - The number of times to print.
     */
    this.printBall = function (N) {
        var i = 0;
        while (i < N) {
            console.log('Ball');
            i++
        }
    };

};

这是等效的构造函数，可动态生成如下所示的相同方法:

Here is an equivalent constructor function that dynamically generates the same methods like this:

var A = function () {

    var me = this;
    var registerPrinter = function (name) {
        me['print' + name] = function (N) {
            var i = 0;
            while (i < N) {
                console.log(name);
                i++;
            }
        };
    };

    registerPrinter('Thing');
    registerPrinter('Ball');
}

由两个构造函数生成的实例的行为是相同的:

The behaviour of the instances generated by the two constructor functions are identical:

> var a = new A();
> a.printBall(4);
Ball
Ball
Ball
Ball

如何使用JSDoc在第二个 A 构造函数中记录生成的方法?

How can I use JSDoc to document the generated methods in the second A constructor function?

registerPrinter 在构造函数的范围内是私有的.可以(并且应该)对其进行记录，但仅在内部使用.这个问题是关于记录生成的 A 实例的公共接口.

registerPrinter is private within the scope of the constructor function. It can (and should) be documented, but it's just used internally. This question is about documenting the resulting public interface of A instances.

推荐答案

@name 为此:

此标记最适合在虚拟注释"中用于代码中不容易看到的符号...

This tag is best used in "virtual comments" for symbols that are not readily visible in the code...

ES6:

/** Class A */
class A {
    constructor () {
        ['Thing', 'Ball'].map((name) => {
            this['print' + name] = (N) => {
                let i = 0;
                while (i < N) {
                    console.log(name);
                    i++;
                }
            };
        });
    }
}

/**
 * @name A#printThing
 * @function
 * @memberof A
 * @description Prints 'Thing'
 * @param {Number} N - The number of times to print.
 */

/**
 * @name A#printBall
 * @function
 * @memberof A
 * @description Prints 'Ball'
 * @param {Number} N - The number of times to print.
 */

ES5:

/**
 * @class A
 */
var A = function () {

    var me = this;
    var registerPrinter = function (name) {
        me['print' + name] = function (N) {
            var i = 0;
            while (i < N) {
                console.log(name);
                i++;
            }
        };
    };

    ['Thing', 'Ball'].map(registerPrinter);

    /**
     * @name A#printThing
     * @function
     * @memberof A
     * @description Prints 'Thing'
     * @param {Number} N - The number of times to print.
     */

    /**
     * @name A#printBall
     * @function
     * @memberof A
     * @description Prints 'Ball'
     * @param {Number} N - The number of times to print.
     */
}

这篇关于JSDoc可以记录动态生成的方法吗?的文章就介绍到这了，希望我们推荐的答案对大家有所帮助，也希望大家多多支持IT屋！