@external
优质
小牛编辑
127浏览
2023-12-01
描述:标识一个外部的类,命名空间,或模块。
别名: @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 */