将名称路径与 JSDoc 一起使用
JSDoc 中的名称路径
🌐 Namepaths in JSDoc
在引用文档中其他地方的 JavaScript 变量时，必须提供一个映射到该变量的唯一标识符。namepath 提供了一种方法来实现这一点，并区分实例成员、静态成员和内部变量。
🌐 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
下面的例子展示了：一个名为“say”的_实例_方法，一个也名为“say”的_内部_函数，以及一个也名为“say”的_静态_方法。这是三个相互独立存在的方法。
🌐 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();
在这种情况下，要引用名为 "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
*/
Namepaths 有一些特殊情况：@模块 名称前缀是“module:”，@external 名称前缀是“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"
*/
上面是一个命名空间示例，其成员名称中包含“异常”字符（哈希字符、破折号，甚至引号）。 要引用这些名称，只需将名称加上引号：chat."#channel"、chat."#channel"."op:announce-motd" 等。 名称内部的引号应使用反斜杠转义：chat."#channel"."say-"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"".