JSDoc3使用路徑名

原文：http://usejsdoc.org/about-namepaths.html

在JSDoc3中的路徑名

如果涉及到一個JavaScript變量指的是在你的文檔中的其他地方，你必須提供映射到該變量的唯一標識符。一個路徑名提供了一種這樣做的方法，和實例成員，靜態成員和內部變量之間的歧義。

在JSDoc3中路徑名基本的語法示例：

myFunction
MyConstructor
MyConstructor#instanceMember
MyConstructor.staticMember
MyConstructor~innerMember // note that JSDoc 2 uses a dash

下面給出了例子：一個被命名爲“say”的實例方法，名爲“say”內部function,和靜態方法也被命名爲“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"
 */

以上是一個命名空間的例子帶有“unusual”的字符在它的成員名稱中（#號，破折號，引號）。參考這些，你只需要引用的名字：chat.“＃channel”chat.“＃channel”.“op：announce-motd”，等等。在名稱內部的引號應該轉義爲反斜槓：chat.”#channel”.”say-\”hello\”“。