@external (synonyms: @host)

.. @external::

同义词

@host

语法

@external <NameOfExternal>

概述

The @external tag identifies a class, namespace, or module that is defined outside of the current package. By using this tag, you can document your package’s extensions to the external symbol, or you can provide information about the external symbol to your package’s users. You can also refer to the external symbol’s namepath in any other JSDoc tag.

The namepath for an external symbol always uses the prefix external: (for example, {@link external:Foo} or @augments external:Foo). However, you can omit this prefix from the @external tag.

注意

You should only add the @external tag to the highest-level symbol that is defined outside of your project. See “Documenting a nested external symbol” for an example.

示例

下面的示例演示如何将内置的``String``对象作为外部文档, 以及新的实例方法``external: String＃rot13``:

Documenting methods added to built-in classes

/**
 * 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 ”``:

Documenting external namespaces

/**
 * 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`的子类. :

Extending an external.

/**
 * 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
 */

You should only add the @external tag to the highest-level symbol that is defined outside of your project. In the following example, the documentation refers to the external class security.TLS. As a result, the @external tag is used to document the external namespace external:security, but not the external class external:security.TLS.

Documenting a nested external symbol

/**
 * 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
 */

.. @host::

同义词

@external