Использование namepaths с JSDoc 3

Содержание

• Namepaths в JSDoc 3
• Связанные ссылки

Namepaths в JSDoc 3

При ссылке на JavaScript-переменную, которая находится в другом месте вашей документации, необходимо предоставить уникальный идентификатор, который сопоставляется с этой переменной. Namepath предоставляет способ сделать это и различить члены экземпляра, статические члены и внутренние переменные.

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

Вы бы использовали три разных синтаксиса namepath, чтобы сослаться на три разных метода:

Person#say  // the instance method named "say."
Person.say  // the static method named "say."
Person~say  // the inner method named "say."

Вы можете задаться вопросом, почему существует синтаксис для ссылки на внутренний метод, когда к этому методу нельзя напрямую обратиться извне функции, в которой он определен. Хотя это правда, и поэтому синтаксис "~" используется редко, возможно вернуть ссылку на внутренний метод из другого метода внутри этого контейнера, поэтому возможно, что какой-либо объект в другом месте вашего кода может заимствовать внутренний метод.

Обратите внимание, что если конструктор имеет член экземпляра, который также является конструктором, вы можете просто объединить namepaths, чтобы сформировать более длинный 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", вы бы использовали следующий namepath: 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
 */

Существуют некоторые особые случаи с namepaths: имена модулей @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"".

Связанные ссылки

• Блочные и встроенные теги
• {@link}