@external

描述:标识一个外部的类，命名空间，或模块。

别名: @host

Syntax（语法）

@external <NameOfExternal>

Overview（概述）

@external标签用来标识一个在当前包外部定义的类，命名空间，或模块。通过使用这个标签，你可以描述你的包的外部标识的扩展，或者您也可以提供关于 外部标识的相关信息给你的包的使用者。你也可以在任何其他JSDoc标签中引用外部标识的namepath（名称路径）。

外部标识引用的路径名 始终需要使用external:前缀：（例如{@link external:Foo}或@augments external:Foo）。 但是，你可以省略@external标记的这个前缀。

注意：您只能在你的项目之外定义的最高级别的标识上添加@external标签，请参见“描述一个嵌套的外部标识”的例子。

Examples（例子）

下面的示例演示如何描述内置的String对象作为external，新的实例方法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
 */