JSDoc 可以记录动态生成的方法吗？

Question

这是一个构造函数 A，它为实例提供了 2 个方法：printThing 和 printBall。我使用 JSDoc 来记录这样的方法：

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++
        }
    };

};

下面是一个等效的构造函数，它动态生成与此相同的方法：

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');
}

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

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

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

编辑：registerPrinter 在构造函数的范围内是私有的。它可以（并且应该）被记录下来，但它只是在内部使用。这个问题是关于记录 A 实例的结果 public 接口。

Answer 1

为什么不只记录编写的代码？

var A = function() {

  var me = this;

  /**
   * [function description]
   * @param  {[type]} name [description]
   * @return {[type]}      [description]
   */
  var registerPrinter = function(name) {

    /**
     * [function description]
     * @param  {[type]} N [description]
     * @return {[type]}   [description]
     */
    me['print' + name] = function(N) {
      var i = 0;
      while (i < N) {
        console.log(name);
        i++;
      }
    };
  };

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

Answer 2

经过一天的文档搜索，这是我能找到的最佳选择。它需要对 A 稍有不同的等效定义，并对 registerPrinter 进行更改。它稍微冗长一些，但是保留了不重复非常相似的方法的可维护性好处，并且更具可读性：

var A = function () {

    var generatePrinter = function (name) {
        return function (N) {
            var i = 0;
            while (i < N) {
                console.log(name);
                i++;
            }
        };
    };

    /**
     * Prints 'Thing'
     * @param {Number} N - The number of times to print.
     */
    this.printThing = generatePrinter('Thing');

    /**
     * Prints 'Ball'
     * @param {Number} N - The number of times to print.
     */
    this.printBall = generatePrinter('Ball');
}

请注意，这不再是将属性 printThing 或 printBall 动态添加到 this（尽管方法仍然是动态生成的）。因此，这不是问题的直接解决方案——它是一种变通方法。 我会接受任何实际记录动态添加属性的未来答案。

Answer 3

@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 可以记录动态生成的方法吗？

Can JSDoc document dynamically generated methods?

javascript

jsdoc