Synonyms

• host

语法

¥Syntax

@external <NameOfExternal>

概述

¥Overview

@external 标记标识当前包外部定义的类、命名空间或模块。通过使用此标签，你可以记录包对外部符号的扩展，也可以向包的用户提供有关外部符号的信息。你还可以在任何其他 JSDoc 标记中引用外部符号的名称路径。

¥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.

外部符号的名称路径始终使用前缀 external:（例如 {@link external:Foo} 或 @augments external:Foo）。但是，你可以在 @external 标记中省略此前缀。

¥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.

注意：你应该只将 @external 标签添加到项目外部定义的最高级别符号中。请参阅“记录嵌套的外部符号”的示例。

¥Note: 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.

示例

¥Examples

以下示例显示如何将内置 String 对象以及新实例方法 external:String#rot13 记录为外部对象：

¥The following example shows how to document the built-in String object as an external, along with the new instance method external:String#rot13:

/**

 * The built in string object.

 * @external String

 * @see {@link https://web.nodejs.cn/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
 */

以下示例记录了添加到外部命名空间 "jQuery.fn" 的新 starfairy 函数：

¥The following example documents a new starfairy function added to the external namespace "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 的子类：

¥In the following example, the class EncryptedRequest is documented as a subclass of the built-in class XMLHttpRequest:

/**

 * The built-in class for sending HTTP requests.

 * @external XMLHttpRequest

 * @see https://web.nodejs.cn/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。

¥ 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.

/**

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