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