You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: tags-external.html
+43-16Lines changed: 43 additions & 16 deletions
Original file line number
Diff line number
Diff line change
@@ -4,7 +4,7 @@
4
4
5
5
<head>
6
6
<metacharset="utf-8">
7
-
<metaname="description" content="Document an external class/namespace/module.">
7
+
<metaname="description" content="Identifies an external class, namespace, or module.">
8
8
<title>Use JSDoc: @external</title>
9
9
<linkrel="stylesheet" href="styles/usejsdoc.css">
10
10
<linkrel="stylesheet" href="styles/prettify.css">
@@ -45,32 +45,40 @@ <h2 id="syntax">Syntax</h2>
45
45
<p><code>@external <NameOfExternal></code>
46
46
</p>
47
47
<h2id="overview">Overview</h2>
48
-
<p>The @external tag is used for documenting a class or namespace or module that is external to the project. It is then known within JSDoc so you can <ahref="tags-augments.html">@extend</a> it, be a
49
-
<ahref="tags-memberof.html">@memberof</a> it and so on as you would any other class/namespace/module.</p>
50
-
<p>When you refer to an external object, prefix "external:" to it - for example, "{@link external:Foo}" or "@augments external:Foo".</p>
48
+
<p>The <code>@external</code> tag identifies a class, namespace, or module that is defined outside of the current package. By using this tag, you can document your
49
+
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
50
+
the external symbol's namepath in any other JSDoc tag.</p>
51
+
<p>The namepath for an external symbol always uses the prefix <code>external:</code> (for example,
52
+
<code>{@link external:Foo}</code> or <code>@augments external:Foo</code>). However, you can omit this prefix from the
53
+
<code>@external</code> tag.</p>
54
+
<p><strong>Note</strong>: You should only add the <code>@external</code> tag to the highest-level symbol that is defined outside of your project. See "<ahref="#nested-external-symbol">Documenting a nested external symbol</a>"
55
+
for an example.
56
+
</p>
51
57
<h2id="examples">Examples</h2>
58
+
<p>The following example shows how to document the built-in <code>String</code> object as an external, along with the new instance method <code>external:String#rot13</code>:</p>
52
59
<figure>
53
-
<figcaption>Documenting methods added to built-in classes.</figcaption><preclass="prettyprint lang-js"><code>/**
60
+
<figcaption>Documenting methods added to built-in classes</figcaption><preclass="prettyprint lang-js"><code>/**
* Create a ROT13-encoded version of the string. Added by the `foo` package.
61
68
* @function external:String#rot13
62
69
* @example
63
70
* var greeting = new String('hello world');
64
71
* console.log( greeting.rot13() ); // uryyb jbeyq
65
72
*/
66
73
</code></pre>
67
74
</figure>
68
-
<p>Suppose we added function <code>rot13</code> to the String class. The above adds documentation for the String class as an external, allowing <code>rot13</code> to be properly documented as an instance member of String.</p>
75
+
<p>The following example documents a new <code>starfairy</code> function added to the external namespace
* Extends the builtin XMLHttpRequest to send data encoded with a secret key.
92
-
* @class EncryptedRequest
99
+
* Extends the built-in `XMLHttpRequest` class to send data encoded with a secret key.
100
+
* @class EncodedRequest
93
101
* @extends external:XMLHttpRequest
94
102
*/
95
103
</code></pre>
96
104
</figure>
97
-
<p>One can even <ahref="tags-augments.html">@extend</a> an external. <code>EncryptedRequest</code> is a class that extends (external) <code>XMLHttpRequest</code>.</p>
105
+
<p>
106
+
<aname="nested-external-symbol"></a>
107
+
You should only add the <code>@external</code> tag to the highest-level symbol that is defined outside of your project. In the following example, the documentation
108
+
refers to the external class
109
+
<code>security.TLS</code>. As a result, the <code>@external</code> tag is used to document the external namespace
110
+
<code>external:security</code>, but <em>not</em> the external class <code>external:security.TLS</code>.</p>
111
+
<figure>
112
+
<figcaption>Documenting a nested external symbol</figcaption><preclass="prettyprint lang-js"><code>/**
113
+
* External namespace for security-related classes.
114
+
* @external security
115
+
* @see http://example.org/docs/security
116
+
*/
117
+
118
+
/**
119
+
* External class that provides Transport Layer Security (TLS) encryption.
0 commit comments