Skip to content

Commit bbe713f

Browse files
hegemonichegemonic
committed
document inheritdoc and override tags (#76)
1 parent a86b8ca commit bbe713f

File tree

5 files changed

+371
-0
lines changed

5 files changed

+371
-0
lines changed

‎content/en/tags-inheritdoc.md

Lines changed: 89 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,89 @@
1+
---
2+
tag: inheritdoc
3+
description: Indicate that a symbol should inherit its parent's documentation.
4+
version: '>=3.3.0'
5+
related:
6+
- tags-override.html
7+
---
8+
9+
## Overview
10+
11+
The `@inheritdoc` tag indicates that a symbol should inherit its documentation from its parent
12+
class. Any other tags that you include in the JSDoc comment will be ignored.
13+
14+
This tag is provided for compatibility with [Closure Compiler][closure]. By default, if you do
15+
not add a JSDoc comment to a symbol, the symbol will inherit documentation from its parent.
16+
17+
The presence of the `@inheritdoc` tag implies the presence of the [`@override` tag][override-tag].
18+
19+
[closure]: https://developers.google.com/closure/compiler/
20+
[override-tag]: tags-override.html
21+
22+
23+
## Examples
24+
25+
The following example shows how a class can indicate that it inherits documentation from its
26+
parent class:
27+
28+
{% example "Class that inherits from a parent class" %}
29+
30+
```js
31+
/**
32+
* @classdesc Abstract class representing a network connection.
33+
* @class
34+
*/
35+
function Connection() {}
36+
37+
/**
38+
* Open the connection.
39+
*/
40+
Connection.prototype.open = function() {
41+
// ...
42+
};
43+
44+
45+
/**
46+
* @classdesc Class representing a socket connection.
47+
* @class
48+
* @augments Connection
49+
*/
50+
function Socket() {}
51+
52+
/** @inheritdoc */
53+
Socket.prototype.open = function() {
54+
// ...
55+
};
56+
```
57+
{% endexample %}
58+
59+
You can get the same result by omitting the JSDoc comment from `Socket#open`:
60+
61+
{% example "Inheriting documentation without the `@inheritdoc` tag" %}
62+
63+
```js
64+
/**
65+
* @classdesc Abstract class representing a network connection.
66+
* @class
67+
*/
68+
function Connection() {}
69+
70+
/**
71+
* Open the connection.
72+
*/
73+
Connection.prototype.open = function() {
74+
// ...
75+
};
76+
77+
78+
/**
79+
* @classdesc Class representing a socket connection.
80+
* @class
81+
* @augments Connection
82+
*/
83+
function Socket() {}
84+
85+
Socket.prototype.open = function() {
86+
// ...
87+
};
88+
```
89+
{% endexample %}

‎content/en/tags-override.md

Lines changed: 62 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,62 @@
1+
---
2+
tag: override
3+
description: Indicate that a symbol overrides its parent.
4+
dictionaries:
5+
- closure
6+
version: '>=3.3.0'
7+
related:
8+
- tags-inheritdoc.html
9+
---
10+
11+
## Overview
12+
13+
The `@override` tag indicates that a symbol overrides a symbol with the same name in a parent class.
14+
15+
This tag is provided for compatibility with [Closure Compiler][closure]. By default, JSDoc
16+
automatically identifies symbols that override a parent.
17+
18+
If your JSDoc comment includes the [`@inheritdoc` tag][inheritdoc-tag], you do not need to include
19+
the `@override` tag. The presence of the `@inheritdoc` tag implies the presence of the `@override`
20+
tag.
21+
22+
[closure]: https://developers.google.com/closure/compiler/
23+
[inheritdoc-tag]: tags-inheritdoc.html
24+
25+
26+
## Example
27+
28+
The following example shows how to indicate that a method overrides a method in its parent class:
29+
30+
{% example "Method that overrides a parent" %}
31+
32+
```js
33+
/**
34+
* @classdesc Abstract class representing a network connection.
35+
* @class
36+
*/
37+
function Connection() {}
38+
39+
/**
40+
* Open the connection.
41+
*/
42+
Connection.prototype.open = function() {
43+
// ...
44+
};
45+
46+
47+
/**
48+
* @classdesc Class representing a socket connection.
49+
* @class
50+
* @augments Connection
51+
*/
52+
function Socket() {}
53+
54+
/**
55+
* Open the socket.
56+
* @override
57+
*/
58+
Socket.prototype.open = function() {
59+
// ...
60+
};
61+
```
62+
{% endexample %}

‎index.html

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -111,6 +111,8 @@ <h2 id="tag-dictionary">Tag Dictionary</h2>
111111
<dd>Document a global object.</dd>
112112
<dt><a href="tags-ignore.html">@ignore</a></dt>
113113
<dd>Omit a symbol from the documentation.</dd>
114+
<dt><a href="tags-inheritdoc.html">@inheritdoc</a></dt>
115+
<dd>Indicate that a symbol should inherit its parent&#39;s documentation.</dd>
114116
<dt><a href="tags-inner.html">@inner</a></dt>
115117
<dd>Document an inner object.</dd>
116118
<dt><a href="tags-instance.html">@instance</a></dt>
@@ -137,6 +139,8 @@ <h2 id="tag-dictionary">Tag Dictionary</h2>
137139
<dd>Document the name of an object.</dd>
138140
<dt><a href="tags-namespace.html">@namespace</a></dt>
139141
<dd>Document a namespace object.</dd>
142+
<dt><a href="tags-override.html">@override</a></dt>
143+
<dd>Indicate that a symbol overrides its parent.</dd>
140144
<dt><a href="tags-param.html">@param</a> (synonyms: @arg, @argument)</dt>
141145
<dd>Document the parameter to a function.</dd>
142146
<dt><a href="tags-private.html">@private</a></dt>

‎tags-inheritdoc.html

Lines changed: 120 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,120 @@
1+
<!DOCTYPE html>
2+
<!-- THIS IS A GENERATED FILE. DO NOT EDIT. -->
3+
<html lang="en">
4+
5+
<head>
6+
<meta charset="utf-8">
7+
<meta name="description" content="Indicate that a symbol should inherit its parent&#39;s documentation.">
8+
<title>Use JSDoc: @inheritdoc</title>
9+
<link rel="stylesheet" href="styles/usejsdoc.css">
10+
<link rel="stylesheet" href="styles/prettify.css">
11+
<link rel="stylesheet" href="styles/css3-github-ribbon.css">
12+
<script src="scripts/prettify.js"></script>
13+
<!--[if lt IE 9]>
14+
<script src="scripts/html5shiv.min.js"></script>
15+
<script src="scripts/html5shiv-printshiv.min.js"></script>
16+
<![endif]-->
17+
</head>
18+
19+
<body>
20+
<header>
21+
<a href="./index.html">@use JSDoc</a>
22+
</header>
23+
<article>
24+
<h1>@inheritdoc</h1>
25+
<h2>Table of Contents</h2>
26+
<ul>
27+
<li>
28+
<a href="#overview">Overview</a>
29+
</li>
30+
<li>
31+
<a href="#examples">Examples</a>
32+
</li>
33+
<li>
34+
<a href="#related-links">Related Links</a>
35+
</li>
36+
</ul>
37+
<h2 id="overview">Overview</h2>
38+
<p>The <code>@inheritdoc</code> tag indicates that a symbol should inherit its documentation from its parent class. Any other tags that you include in the JSDoc
39+
comment will be ignored.</p>
40+
<p>This tag is provided for compatibility with <a href="https://developers.google.com/closure/compiler/">Closure Compiler</a>. By default, if you do not add a JSDoc
41+
comment to a symbol, the symbol will inherit documentation from its parent.</p>
42+
<p>The presence of the <code>@inheritdoc</code> tag implies the presence of the <a href="tags-override.html"><code>@override</code> tag</a>.</p>
43+
<h2 id="examples">Examples</h2>
44+
<p>The following example shows how a class can indicate that it inherits documentation from its parent class:</p>
45+
<figure>
46+
<figcaption>Class that inherits from a parent class</figcaption><pre class="prettyprint lang-js"><code>/**
47+
* @classdesc Abstract class representing a network connection.
48+
* @class
49+
*/
50+
function Connection() {}
51+
52+
/**
53+
* Open the connection.
54+
*/
55+
Connection.prototype.open = function() {
56+
// ...
57+
};
58+
59+
60+
/**
61+
* @classdesc Class representing a socket connection.
62+
* @class
63+
* @augments Connection
64+
*/
65+
function Socket() {}
66+
67+
/** @inheritdoc */
68+
Socket.prototype.open = function() {
69+
// ...
70+
};
71+
</code></pre>
72+
</figure>
73+
<p>You can get the same result by omitting the JSDoc comment from <code>Socket#open</code>:</p>
74+
<figure>
75+
<figcaption>Inheriting documentation without the <code>@inheritdoc</code> tag</figcaption><pre class="prettyprint lang-js"><code>/**
76+
* @classdesc Abstract class representing a network connection.
77+
* @class
78+
*/
79+
function Connection() {}
80+
81+
/**
82+
* Open the connection.
83+
*/
84+
Connection.prototype.open = function() {
85+
// ...
86+
};
87+
88+
89+
/**
90+
* @classdesc Class representing a socket connection.
91+
* @class
92+
* @augments Connection
93+
*/
94+
function Socket() {}
95+
96+
Socket.prototype.open = function() {
97+
// ...
98+
};
99+
</code></pre>
100+
</figure>
101+
<h2 id="related-links">Related Links</h2>
102+
<p>
103+
<a href="tags-override.html">@override</a>
104+
</p>
105+
</article>
106+
<footer>
107+
<a class="license-badge" href="http://creativecommons.org/licenses/by-sa/3.0/">
108+
<img alt="Creative Commons License" class="license-badge" src="images/cc-by-sa.svg" width="80" height="15" />
109+
</a>
110+
<br> Copyright &#169; 2011-2014 the
111+
<a href="https://github.com/jsdoc3/jsdoc3.github.com/contributors">contributors</a> to the JSDoc 3 documentation project.
112+
<br> This website is <a href="https://github.com/jsdoc3/jsdoc3.github.com">open source</a> and is licensed under the <a rel="license" href="http://creativecommons.org/licenses/by-sa/3.0/">
113+
Creative Commons Attribution-ShareAlike 3.0 Unported License</a>.
114+
</footer>
115+
<script type="text/javascript">
116+
prettyPrint();
117+
</script>
118+
</body>
119+
120+
</html>

‎tags-override.html

Lines changed: 96 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,96 @@
1+
<!DOCTYPE html>
2+
<!-- THIS IS A GENERATED FILE. DO NOT EDIT. -->
3+
<html lang="en">
4+
5+
<head>
6+
<meta charset="utf-8">
7+
<meta name="description" content="Indicate that a symbol overrides its parent.">
8+
<title>Use JSDoc: @override</title>
9+
<link rel="stylesheet" href="styles/usejsdoc.css">
10+
<link rel="stylesheet" href="styles/prettify.css">
11+
<link rel="stylesheet" href="styles/css3-github-ribbon.css">
12+
<script src="scripts/prettify.js"></script>
13+
<!--[if lt IE 9]>
14+
<script src="scripts/html5shiv.min.js"></script>
15+
<script src="scripts/html5shiv-printshiv.min.js"></script>
16+
<![endif]-->
17+
</head>
18+
19+
<body>
20+
<header>
21+
<a href="./index.html">@use JSDoc</a>
22+
</header>
23+
<article>
24+
<h1>@override</h1>
25+
<h2>Table of Contents</h2>
26+
<ul>
27+
<li>
28+
<a href="#overview">Overview</a>
29+
</li>
30+
<li>
31+
<a href="#example">Example</a>
32+
</li>
33+
<li>
34+
<a href="#related-links">Related Links</a>
35+
</li>
36+
</ul>
37+
<h2 id="overview">Overview</h2>
38+
<p>The <code>@override</code> tag indicates that a symbol overrides a symbol with the same name in a parent class.</p>
39+
<p>This tag is provided for compatibility with <a href="https://developers.google.com/closure/compiler/">Closure Compiler</a>. By default, JSDoc automatically identifies
40+
symbols that override a parent.</p>
41+
<p>If your JSDoc comment includes the <a href="tags-inheritdoc.html"><code>@inheritdoc</code> tag</a>, you do not need to include the <code>@override</code> tag.
42+
The presence of the <code>@inheritdoc</code> tag implies the presence of the <code>@override</code> tag.
43+
</p>
44+
<h2 id="example">Example</h2>
45+
<p>The following example shows how to indicate that a method overrides a method in its parent class:</p>
46+
<figure>
47+
<figcaption>Method that overrides a parent</figcaption><pre class="prettyprint lang-js"><code>/**
48+
* @classdesc Abstract class representing a network connection.
49+
* @class
50+
*/
51+
function Connection() {}
52+
53+
/**
54+
* Open the connection.
55+
*/
56+
Connection.prototype.open = function() {
57+
// ...
58+
};
59+
60+
61+
/**
62+
* @classdesc Class representing a socket connection.
63+
* @class
64+
* @augments Connection
65+
*/
66+
function Socket() {}
67+
68+
/**
69+
* Open the socket.
70+
* @override
71+
*/
72+
Socket.prototype.open = function() {
73+
// ...
74+
};
75+
</code></pre>
76+
</figure>
77+
<h2 id="related-links">Related Links</h2>
78+
<p>
79+
<a href="tags-inheritdoc.html">@inheritdoc</a>
80+
</p>
81+
</article>
82+
<footer>
83+
<a class="license-badge" href="http://creativecommons.org/licenses/by-sa/3.0/">
84+
<img alt="Creative Commons License" class="license-badge" src="images/cc-by-sa.svg" width="80" height="15" />
85+
</a>
86+
<br> Copyright &#169; 2011-2014 the
87+
<a href="https://github.com/jsdoc3/jsdoc3.github.com/contributors">contributors</a> to the JSDoc 3 documentation project.
88+
<br> This website is <a href="https://github.com/jsdoc3/jsdoc3.github.com">open source</a> and is licensed under the <a rel="license" href="http://creativecommons.org/licenses/by-sa/3.0/">
89+
Creative Commons Attribution-ShareAlike 3.0 Unported License</a>.
90+
</footer>
91+
<script type="text/javascript">
92+
prettyPrint();
93+
</script>
94+
</body>
95+
96+
</html>

0 commit comments

Comments
 (0)