Javascript JSDoc：如何记录'var self=this；`？

只要您使用

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

这将生成带有“类人”页面的文档，其中将

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

此示例生成一个

类Person

页面，但它没有

名称

成员或任何方法

我已经看到，您可以到处使用

@memberof

手动将每个成员和方法附加到类中，但这真的很冗长，我想知道是否有办法告诉JSDoc

self

引用该类

---

（顺便说一句，我正在使用JSDoc 3.4，以防万一这很重要。）

可以使用

@alias

注释告诉JSDoc将

self

作为类的引用。实际上，从技术上讲，您需要将

self

别名为类的原型，而不仅仅是类本身的名称（这会以我不完全理解的方式破坏内容）。要执行此操作，您需要将

@alias

设置为

Person#

1：

---

1:从技术上讲，

Person#

等同于

Person.prototype

，因为后面的

#

指的是对象的原型（据我所知，可以更正）。也就是说，

这个

实际上指的是一个实例，它与原型不同，所以我建议不要使用这个符号，因为它会使注释更加混乱。幸运的是，prototype方法和true instance方法之间的JSDoc输出没有区别，所以不要太担心

Person

符号

工作原理相同的备选方案，包括完整性，但可能应避免：

// ...

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

// ...

你让这个（请原谅双关语）变得更复杂了。你的设计有很多问题

您不需要使用

此

来设置原型。我非常喜欢将对象

实例化

与

初始化

范例分开，如下所示：

/** @class */
function Person() {}

Person.prototype =
{
    /** This person's name
     * @return {Person}
     */
    init: function(name)
    {
        this.name = name;

        return this;
    },
};

问候语已在对象上起作用，您不需要传入第二个对象：

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

这也简化了日志问候语：

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

但是，假设您确实希望将第二个对象（person）传递给您的

日志问候语

，则它错误地传递了

类

，而不是

对象

。应该是这样的：

/** 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)); // BUG: was Person instead of person
};

您不应该使用

self

来设置原型——您首先错误地使用了使用

self

的原因：它们用于需要引用对象的回调

例如，让我们在重命名某人时添加回调：

        rename: function(newName) {
            var self = this;
            var cbRename = function() {
                self.onRename( self.name, newName ); // Why self is needed
                self.name = newName;
            };

            setTimeout( cbRename, 1 );
        },

        /** Callback triggered on rename */
        onRename: function(oldName,newName) {
            console.log( "The person formally known as: '" + oldName + "'" );
            console.log( "Is now known as: '"              + newName + "'" );
        },

将其全部放在一个示例中：

/**@class*/
函数Person（）{}
个人原型=
{
/**此人姓名
*@return{Person}
*/
init：函数（名称）
{
this.name=名称；
归还这个；
},
/**问候某人*/
问候：函数（）{
返回“你好，”+this.name；
},
/**将问候语记录到浏览器控制台*/
logGreeting:function（）{
log（this.greet（））；
},
重命名：函数（newName）{
var self=这个；
var cbRename=函数（）{
self.onRename（self.name，newName）；
self.name=newName；
};
setTimeout（cbRename，1）；
},
/**重命名时触发回调*/
onRename：函数（oldName、newName）{
log（“正式名称为：“+oldName+””）的人；
log（“现在称为：“+newName+””）；
},
};
var alice=newperson（）.init（'alice'）；
console.log（alice）；
alice.logGreeting（）；
重命名（'Bob'）

为什么要使用变量来接收

此

而不是将

此

与箭头函数一起使用

/**@class*/
职能人员（姓名）{
/**此人姓名*/
this.name=名称；
/**问候某人*/
this.greet=功能（人）{
返回“你好，”+person.name；
};
/**将问候语记录到浏览器控制台*/
this.logGreeting=函数（个人）{
console.log（this.greet（person））；
};
/**延迟一段时间后，将问候语记录到浏览器控制台*/
this.logGreetingDelayed=功能（人员，延迟）{
setTimeout（（）=>this.logGreeting（person），延迟）；
};
}

如果您想记录此（例如使用私有方法），您可以使用JSDoc

@此

：

/**@class*/
职能人员（姓名）{
/**此人姓名*/
this.name=名称；
/**问候某人*/
this.greet=功能（人）{
返回“你好，”+person.name；
};
/**将问候语记录到浏览器控制台*/
this.logGreeting=函数（个人）{
打电话给（这个人）；
};
/**延迟一段时间后，将问候语记录到浏览器控制台*/
this.logGreetingDelayed=功能（人员，延迟）{
setTimeout（（）=>this.logGreeting（person），延迟）；
};
}
//私有方法
/**
*@这个人
*@param{Person}Person
*/
功能专用问候语（人）{
console.log（this.greet（person））；
}

只需FWIW，您可以在定义这些属性时使用

this

，并且只在函数中使用

self

。但是如果你想在代码中保持一致性，我完全可以看到你在做什么。正如@T.J.Crowder所说，这里根本不需要

self

。在传递给

setTimeout

的函数中，您可能认为您需要它的唯一位置是，您可以说

setTimeout（（）=>this.logGreeting（person），delay）

@torazaburo：好的，生成对象的用例可能是将其中的每一个用作简单的回调。如果是，在ES201中

        rename: function(newName) {
            var self = this;
            var cbRename = function() {
                self.onRename( self.name, newName ); // Why self is needed
                self.name = newName;
            };

            setTimeout( cbRename, 1 );
        },

        /** Callback triggered on rename */
        onRename: function(oldName,newName) {
            console.log( "The person formally known as: '" + oldName + "'" );
            console.log( "Is now known as: '"              + newName + "'" );
        },