Skip to content

Commit 353a172

Browse files
committed
clarify external tag docs (#35)
1 parent f85d03e commit 353a172

File tree

3 files changed

+96
-40
lines changed

3 files changed

+96
-40
lines changed

content/en/tags-external.md

Lines changed: 52 additions & 23 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
---
22
tag: external
3-
description: Document an external class/namespace/module.
3+
description: Identifies an external class, namespace, or module.
44
synonyms:
55
- host
66
---
@@ -12,30 +12,39 @@ synonyms:
1212

1313
## Overview
1414

15-
The @external tag is used for documenting a class or namespace or module that is external to the
16-
project. It is then known within JSDoc so you can [@extend][augments-tag] it, be a
17-
[@memberof][memberof-tag] it and so on as you would any other class/namespace/module.
15+
The `@external` tag identifies a class, namespace, or module that is defined outside of the current
16+
package. By using this tag, you can document your package's extensions to the external symbol, or
17+
you can provide information about the external symbol to your package's users. You can also refer to
18+
the external symbol's namepath in any other JSDoc tag.
1819

19-
When you refer to an external object, prefix "external:" to it - for example, "{@link external:Foo}"
20-
or "@augments external:Foo".
20+
The namepath for an external symbol always uses the prefix `external:` (for example,
21+
`{@link external:Foo}` or `@augments external:Foo`). However, you can omit this prefix from the
22+
`@external` tag.
23+
24+
**Note**: You should only add the `@external` tag to the highest-level symbol that is defined
25+
outside of your project. See "[Documenting a nested external symbol][nested-external]" for an
26+
example.
2127

2228
[augments-tag]: tags-augments.html
2329
[memberof-tag]: tags-memberof.html
24-
30+
[nested-external]: #nested-external-symbol
2531

2632
## Examples
2733

28-
{% example "Documenting methods added to built-in classes." %}
34+
The following example shows how to document the built-in `String` object as an external, along with
35+
the new instance method `external:String#rot13`:
36+
37+
{% example "Documenting methods added to built-in classes" %}
2938

3039
```js
3140
/**
3241
* The built in string object.
3342
* @external String
34-
* @see {@link https://developer.mozilla.org/en/JavaScript/Reference/Global_Objects/String String}
43+
* @see {@link https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String|String}
3544
*/
3645

3746
/**
38-
* Adds a new method to the built-in string.
47+
* Create a ROT13-encoded version of the string. Added by the `foo` package.
3948
* @function external:String#rot13
4049
* @example
4150
* var greeting = new String('hello world');
@@ -44,16 +53,16 @@ or "@augments external:Foo".
4453
```
4554
{% endexample %}
4655

47-
Suppose we added function `rot13` to the String class. The above adds documentation for the String
48-
class as an external, allowing `rot13` to be properly documented as an instance member of String.
56+
The following example documents a new `starfairy` function added to the external namespace
57+
`"jQuery.fn"`:
4958

50-
{% example "Documenting external namespaces." %}
59+
{% example "Documenting external namespaces" %}
5160

5261
```js
5362
/**
5463
* The jQuery plugin namespace.
5564
* @external "jQuery.fn"
56-
* @see {@link http://docs.jquery.com/Plugins/Authoring The jQuery Plugin Guide}
65+
* @see {@link http://learn.jquery.com/plugins/|jQuery Plugins}
5766
*/
5867

5968
/**
@@ -63,27 +72,47 @@ class as an external, allowing `rot13` to be properly documented as an instance
6372
```
6473
{% endexample %}
6574

66-
The above creates `jQuery.fn` as an external namespace, allowing us to document our `starfairy`
67-
function as a member of it.
75+
In the following example, the class `EncryptedRequest` is documented as a subclass of the built-in
76+
class `XMLHttpRequest`:
6877

6978
{% example "Extending an external." %}
7079

7180
```js
7281
/**
73-
* Namespace provided by the browser.
82+
* The built-in class for sending HTTP requests.
7483
* @external XMLHttpRequest
75-
* @see https://developer.mozilla.org/en/xmlhttprequest
84+
* @see https://developer.mozilla.org/en-US/docs/Web/API/XMLHttpRequest
7685
*/
7786

7887
/**
79-
* Extends the built in XMLHttpRequest to send data encoded with a secret key.
80-
* @class EncryptedRequest
88+
* Extends the built-in `XMLHttpRequest` class to send data encoded with a secret key.
89+
* @class EncodedRequest
8190
* @extends external:XMLHttpRequest
8291
*/
8392
```
8493
{% endexample %}
8594

86-
One can even [@extend][augments-tag] an external. `EncryptedRequest` is a class that extends
87-
(external) `XMLHttpRequest`.
88-
8995
[augments-tag]: tags-augments.html
96+
97+
<a name="nested-external-symbol"></a>
98+
You should only add the `@external` tag to the highest-level symbol that is defined outside of your
99+
project. In the following example, the documentation refers to the external class
100+
`security.TLS`. As a result, the `@external` tag is used to document the external namespace
101+
`external:security`, but _not_ the external class `external:security.TLS`.
102+
103+
{% example "Documenting a nested external symbol" %}
104+
105+
```js
106+
/**
107+
* External namespace for security-related classes.
108+
* @external security
109+
* @see http://example.org/docs/security
110+
*/
111+
112+
/**
113+
* External class that provides Transport Layer Security (TLS) encryption.
114+
* @class TLS
115+
* @memberof external:security
116+
*/
117+
```
118+
{% endexample %}

index.html

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -93,7 +93,7 @@ <h2 id="block-tags">Block Tags</h2>
9393
<dt><a href="tags-exports.html">@exports</a></dt>
9494
<dd>Identify the member that is exported by a JavaScript module.</dd>
9595
<dt><a href="tags-external.html">@external</a> (synonyms: @host)</dt>
96-
<dd>Document an external class/namespace/module.</dd>
96+
<dd>Identifies an external class, namespace, or module.</dd>
9797
<dt><a href="tags-file.html">@file</a> (synonyms: @fileoverview, @overview)</dt>
9898
<dd>Describe a file.</dd>
9999
<dt><a href="tags-fires.html">@fires</a> (synonyms: @emits)</dt>

tags-external.html

Lines changed: 43 additions & 16 deletions
Original file line numberDiff line numberDiff line change
@@ -4,7 +4,7 @@
44

55
<head>
66
<meta charset="utf-8">
7-
<meta name="description" content="Document an external class/namespace/module.">
7+
<meta name="description" content="Identifies an external class, namespace, or module.">
88
<title>Use JSDoc: @external</title>
99
<link rel="stylesheet" href="styles/usejsdoc.css">
1010
<link rel="stylesheet" href="styles/prettify.css">
@@ -45,32 +45,40 @@ <h2 id="syntax">Syntax</h2>
4545
<p><code>@external &lt;NameOfExternal&gt;</code>
4646
</p>
4747
<h2 id="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 <a href="tags-augments.html">@extend</a> it, be a
49-
<a href="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 &quot;external:&quot; to it - for example, &quot;{@link external:Foo}&quot; or &quot;@augments external:Foo&quot;.</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&#39;s extensions to the external symbol, or you can provide information about the external symbol to your package&#39;s users. You can also refer to
50+
the external symbol&#39;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 &quot;<a href="#nested-external-symbol">Documenting a nested external symbol</a>&quot;
55+
for an example.
56+
</p>
5157
<h2 id="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>
5259
<figure>
53-
<figcaption>Documenting methods added to built-in classes.</figcaption><pre class="prettyprint lang-js"><code>/**
60+
<figcaption>Documenting methods added to built-in classes</figcaption><pre class="prettyprint lang-js"><code>/**
5461
* The built in string object.
5562
* @external String
56-
* @see {@link https://developer.mozilla.org/en/JavaScript/Reference/Global_Objects/String String}
63+
* @see {@link https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String|String}
5764
*/
5865

5966
/**
60-
* Adds a new method to the built-in string.
67+
* Create a ROT13-encoded version of the string. Added by the `foo` package.
6168
* @function external:String#rot13
6269
* @example
6370
* var greeting = new String('hello world');
6471
* console.log( greeting.rot13() ); // uryyb jbeyq
6572
*/
6673
</code></pre>
6774
</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
76+
<code>&quot;jQuery.fn&quot;</code>:</p>
6977
<figure>
70-
<figcaption>Documenting external namespaces.</figcaption><pre class="prettyprint lang-js"><code>/**
78+
<figcaption>Documenting external namespaces</figcaption><pre class="prettyprint lang-js"><code>/**
7179
* The jQuery plugin namespace.
7280
* @external "jQuery.fn"
73-
* @see {@link http://docs.jquery.com/Plugins/Authoring The jQuery Plugin Guide}
81+
* @see {@link http://learn.jquery.com/plugins/|jQuery Plugins}
7482
*/
7583

7684
/**
@@ -79,22 +87,41 @@ <h2 id="examples">Examples</h2>
7987
*/
8088
</code></pre>
8189
</figure>
82-
<p>The above creates <code>jQuery.fn</code> as an external namespace, allowing us to document our <code>starfairy</code> function as a member of it.</p>
90+
<p>In the following example, the class <code>EncryptedRequest</code> is documented as a subclass of the built-in class <code>XMLHttpRequest</code>:</p>
8391
<figure>
8492
<figcaption>Extending an external.</figcaption><pre class="prettyprint lang-js"><code>/**
85-
* Namespace provided by the browser.
93+
* The built-in class for sending HTTP requests.
8694
* @external XMLHttpRequest
87-
* @see https://developer.mozilla.org/en/xmlhttprequest
95+
* @see https://developer.mozilla.org/en-US/docs/Web/API/XMLHttpRequest
8896
*/
8997

9098
/**
91-
* Extends the built in 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
93101
* @extends external:XMLHttpRequest
94102
*/
95103
</code></pre>
96104
</figure>
97-
<p>One can even <a href="tags-augments.html">@extend</a> an external. <code>EncryptedRequest</code> is a class that extends (external) <code>XMLHttpRequest</code>.</p>
105+
<p>
106+
<a name="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><pre class="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.
120+
* @class TLS
121+
* @memberof external:security
122+
*/
123+
</code></pre>
124+
</figure>
98125
</article>
99126
<footer>
100127
<a class="license-badge" href="http://creativecommons.org/licenses/by-sa/3.0/">

0 commit comments

Comments
 (0)