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 标签添加到在项目外部定义的最高级别符号。有关示例，请参见 "记录嵌套的外部符号"。

示例

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

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