@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""。