@external

Содержание

• Синонимы
• Синтаксис
• Обзор
• Примеры

Синонимы

@host

Синтаксис

@external <NameOfExternal>

Обзор

Тег @external отмечает класс, пространство имён или модуль, определённый вне текущего пакета. Используя этот тег, вы можете документировать расширения вашего пакета для внешнего символа или предоставить информацию об этом внешнем символе пользователям вашего пакета. Вы также можете ссылаться на имя внешнего символа в любом другом теге JSDoc.

Путь к имени внешнего символа всегда использует префикс external: (например, {@link external:Foo} или @augments external:Foo). Однако вы можете опустить этот префикс из тега @external.

Примечание: Вы должны добавить тег @external только к самому верхнему символу, определённому вне вашего проекта. Смотрите "Документирование вложенного внешнего символа" для примера.

Примеры

Следующий пример демонстрирует, как документировать встроенный объект String как внешний, вместе с новым методом экземпляра external:String#rot13:

/**
 * The built in string object.
 * @external String
 * @see {@link https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String|String}
 */

/**
 * Create a ROT13-encoded version of the string. Added by the `foo` package.
 * @function external:String#rot13
 * @example
 * var greeting = new String('hello world');
 * console.log( greeting.rot13() ); // uryyb jbeyq
 */

Следующий пример документирует новую функцию starfairy , добавленную к внешнему пространству имён "jQuery.fn":

/**
 * The jQuery plugin namespace.
 * @external "jQuery.fn"
 * @see {@link http://learn.jquery.com/plugins/|jQuery Plugins}
 */

/**
 * A jQuery plugin to make stars fly around your home page.
 * @function external:"jQuery.fn".starfairy
 */

В следующем примере класс EncryptedRequest документируется как подкласс встроенного класса XMLHttpRequest:

/**
 * The built-in class for sending HTTP requests.
 * @external XMLHttpRequest
 * @see https://developer.mozilla.org/en-US/docs/Web/API/XMLHttpRequest
 */

/**
 * Extends the built-in `XMLHttpRequest` class to send data encoded with a secret key.
 * @class EncodedRequest
 * @extends external:XMLHttpRequest
 */

Вы должны добавить тег @external только к самому верхнему символу, определённому вне вашего проекта. В следующем примере документация ссылается на внешний класс security.TLS. В результате тег @external используется для документирования внешнего пространства имён external:security, но не внешнего класса external:security.TLS.

/**
 * External namespace for security-related classes.
 * @external security
 * @see http://example.org/docs/security
 */

/**
 * External class that provides Transport Layer Security (TLS) encryption.
 * @class TLS
 * @memberof external:security
 */