将名称路径与 JSDoc 一起使用
JSDoc 中的名称路径
¥Namepaths in JSDoc
当引用文档中其他位置的 JavaScript 变量时，你必须提供映射到该变量的唯一标识符。名称路径提供了一种方法来消除实例成员、静态成员和内部变量之间的歧义。
¥When referring to a JavaScript variable that is elsewhere in your documentation, you must provide a unique identifier that maps to that variable. A namepath provides a way to do so and disambiguate between instance members, static members and inner variables.
myFunction
MyConstructor
MyConstructor#instanceMember
MyConstructor.staticMember
MyConstructor~innerMember // note that JSDoc 2 uses a dash
下面的例子显示：名为 "说，" 的实例方法、也名为 "说，" 的内部函数和也名为 "说。" 的静态方法。这是三个不同的方法，彼此独立存在。
¥The example below shows: an instance method named "say," an inner function also named "say," and a static method also named "say." These are three distinct methods that all exist independently of one another.
/** @constructor */
Person = function() {
this.say = function() {
return "I'm an instance.";
}
function say() {
return "I'm inner.";
}
}
Person.say = function() {
return "I'm static.";
}
var p = new Person();
p.say(); // I'm an instance.
Person.say(); // I'm static.
// there is no way to directly access the inner function from here
你将使用三种不同的名称路径语法来引用三种不同的方法：
¥You would use three different namepath syntaxes to refer to the three different methods:
Person#say // the instance method named "say."
Person.say // the static method named "say."
Person~say // the inner method named "say."
你可能想知道，当无法从定义它的函数外部直接访问该方法时，为什么有一种语法来引用该方法。虽然这是事实，因此很少使用 "~" 语法，但可以从该容器内的另一个方法返回对内部方法的引用，因此代码中其他位置的某些对象可能会借用内部方法。
¥You might wonder why there is a syntax to refer to an inner method when that method isn't directly accessible from outside the function it is defined in. While that is true, and thus the "~" syntax is rarely used, it is possible to return a reference to an inner method from another method inside that container, so it is possible that some object elsewhere in your code might borrow an inner method.
请注意，如果构造函数有一个实例成员也是构造函数，则可以简单地将名称路径链接在一起以形成更长的名称路径：
¥Note that if a constructor has an instance member that is also a constructor, you can simply chain the namepaths together to form a longer namepath:
/** @constructor */
Person = function() {
/** @constructor */
this.Idea = function() {
this.consider = function(){
return "hmmm";
}
}
}
var p = new Person();
var i = new p.Idea();
i.consider();
在本例中，要引用名为 "考虑，" 的方法，你将使用以下名称路径：Person#Idea#consider
¥In this case, to refer to the method named "consider," you would use the following namepath:
Person#Idea#consider
此链接可与连接符号的任意组合一起使用：# . ~
¥This chaining can be used with any combination of the connecting symbols: # . ~
/** A module. Its name is module:foo/bar.
* @module foo/bar
*/
/** The built in string object. Its name is external:String.
* @external String
*/
/** An event. Its name is module:foo/bar.event:MyEvent.
* @event module:foo/bar.event:MyEvent
*/
名称路径有一些特殊情况：@module 名称以 "模块：" 为前缀，@external 名称以 "外部的：" 为前缀，@event 名称以 "事件：" 为前缀。
¥There are some special cases with namepaths: @module names are prefixed by "module:", @external names are prefixed by "external:", and @event names are prefixed by "event:".
/** @namespace */
var chat = {
/**
* Refer to this by {@link chat."#channel"}.
* @namespace
*/
"#channel": {
/**
* Refer to this by {@link chat."#channel".open}.
* @type {boolean}
* @defaultvalue
*/
open: true,
/**
* Internal quotes have to be escaped by backslash. This is
* {@link chat."#channel"."say-\"hello\""}.
*/
'say-"hello"': function (msg) {}
}
};
/**
* Now we define an event in our {@link chat."#channel"} namespace.
* @event chat."#channel"."op:announce-motd"
*/
上面是一个命名空间的示例，其成员名称中包含 "unusual" 个字符（哈希字符、破折号，甚至引号）。要引用这些，你只需引用名称：聊天."＃渠道"、聊天."＃渠道"."op：公告-motd" 等等。名称中的内部引号应使用反斜杠转义：聊天."＃渠道"."说-"hello""。
¥Above is an example of a namespace with "unusual" characters in its member names (the hash character, dashes, even quotes). To refer to these you just need quote the names: chat."#channel", chat."#channel"."op:announce-motd", and so on. Internal quotes in names should be escaped with backslashes: chat."#channel"."say-"hello"".