@use JSDoc

使用 JSDoc 中的名称路径

JSDoc 中的名称路径

在引用文档中其他位置的 JavaScript 变量时，您必须提供映射到该变量的唯一标识符。名称路径提供了一种执行此操作并区分实例成员、静态成员和内部变量的方法。

JSDoc 中名称路径的基本语法示例
myFunction
MyConstructor
MyConstructor#instanceMember
MyConstructor.staticMember
MyConstructor~innerMember // note that JSDoc 2 uses a dash

以下示例显示：一个名为“say”的实例方法，一个也名为“say”的内部函数，以及一个也名为“say”的静态方法。这三个不同的方法彼此独立存在。

使用文档标记来描述您的代码。
/** @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

您将使用三种不同的名称路径语法来引用这三个不同的方法

使用文档标记来描述您的代码。
Person#say  // the instance method named "say."
Person.say  // the static method named "say."
Person~say  // the inner method named "say."

您可能会疑惑，为什么存在引用内部方法的语法，因为该方法无法直接从定义它的函数外部访问。虽然这是真的，因此很少使用“~”语法，但可以从该容器中的另一个方法返回对内部方法的引用，因此您的代码中的其他位置的某个对象可能会借用一个内部方法。

请注意，如果构造函数具有也是构造函数的实例成员，则可以简单地将名称路径链接在一起以形成更长的名称路径

使用文档标记来描述您的代码。
/** @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

此链接可与连接符号的任何组合一起使用：# . ~

特殊情况：模块、外部和事件。
/** 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 名称以“module:”为前缀，@external 名称以“external:”为前缀，@event 名称以“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””。