javascript - JSDoc:如何记录 `var self = this;` ？

Question

只要您使用 this 关键字，JSDoc 就非常擅长获取定义在类上的方法和属性，例如:

/** @class */
function Person(name) {
  /** This person's name */
  this.name = name;

  /** Greet someone */
  this.greet = function(person) {
    return 'Hey there, '+person.name;
  };

  /** Log a greeting to the browser console */
  this.logGreeting = function(person) {
    console.log(this.greet(Person));
  };
}

这将生成带有“Class Person”页面的文档，其中将 name 列为成员，将 greet() 和 logGreeting() 列为方法.

但是当我遇到需要使用 self = this 模式的复杂情况时，事情就开始崩溃了:

/** @class */
function Person(name) {
  var self = this;

  /** This person's name */
  self.name = name;

  /** Greet someone */
  self.greet = function(person) {
    return 'Hey there, '+person.name;
  };

  /** Log a greeting to the browser console */
  self.logGreeting = function(person) {
    console.log(self.greet(Person));
  };

  /** Log a greeting to the browser console after some delay */
  self.logGreetingDelayed = function(person, delay) {
    setTimeout(function() { self.logGreeting(person); }, delay);
  };
}

此示例生成一个 Class Person 页面，但它没有 name 成员或任何方法。

我看到你可以到处使用 @memberof 来手动将每个成员和方法附加到类中，但这真的很冗长，我想知道是否有办法告诉 JSDoc self 指的是类。

(顺便说一句，我正在使用 JSDoc 3.4，以防万一。)

Answer 1

@alias 注释可用于告诉 JSDoc 将 self 视为对该类的引用。实际上，从技术上讲，您需要为类的 prototype 添加 self 的别名，而不仅仅是类本身的名称(这会以我不完全理解的方式破坏内容) .为此，您需要将 @alias 设置为 Person#¹:

/** @class */
function Person(name) {
  /** @alias Person# */
  var self = this;

  /** This person's name */
  self.name = name;

  /** Greet someone */
  self.greet = function(person) {
    return 'Hey there, '+person.name;
  };

  /** Log a greeting to the browser console */
  self.logGreeting = function(person) {
    console.log(self.greet(Person));
  };

  /** Log a greeting to the browser console after some delay */
  self.logGreetingDelayed = function(person, delay) {
    setTimeout(function() { self.logGreeting(person); }, delay);
  };
}

---

1:从技术上讲，Person# 等同于 Person.prototype，因为结尾的 # 指的是对象的原型(prototype)(据我所知；可以更正)。也就是说，this 实际上指的是一个实例，它与原型(prototype)不相同，所以我建议不要使用这种表示法，因为它会使注释更加困惑。幸运的是，原型(prototype)方法和真正的实例方法之间的 JSDoc 输出没有区别，所以不必太担心 Person# 表示法。

工作相同的替代方案，为了完整性而包括在内，但可能应该避免:

// ...

/** @alias Person.prototype */
var self = this;

// ...