8000 document `interface` and `implements` tags (#60) · removed-usr/jsdoc.github.io@cb76d33 · GitHub
[go: up one dir, main page]
Skip to content

Commit cb76d33

Browse files
hegemonichegemonic
committed
document interface and implements tags (jsdoc#60)
1 parent 1480f8f commit cb76d33

File tree

5 files changed

+401
-0
lines changed

5 files changed

+401
-0
lines changed

‎content/en/tags-implements.md

Lines changed: 76 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,76 @@
1+
---
2+
tag: implements
3+
description: This symbol implements an interface.
4+
version: '>=3.3.0'
5+
related:
6+
- tags-interface.html
7+
---
8+
9+
## Syntax
10+
11+
`@implements {typeExpression}`
12+
13+
14+
## Overview
15+
16+
The `@implements` tag indicates that a symbol implements an interface.
17+
18+
Add the `@implements` tag to the top-level symbol that implements the interface (for example, a
19+
constructor function). You do not need to add the `@implements` tag to each member of the
20+
implementation (for example, the implementation's instance methods).
21+
22+
If you do not document one of the symbols in the implementation, JSDoc will automatically use the
23+
interface's documentation for that symbol.
24+
25+
26+
## Examples
27+
28+
In the following example, the `TransparentColor` class implements the `Color` interface and adds
29+
a `TransparentColor#rgba` method.
30+
31+
{% example "Using the @implements tag" %}
32+
33+
```js
34+
/**
35+
* Interface for classes that represent a color.
36+
*
37+
* @interface
38+
*/
39+
function Color() {}
40+
41+
/**
42+
* Get the color as an array of red, green, and blue values, represented as
43+
* decimal numbers between 0 and 1.
44+
*
45+
* @returns {Array<number>} An array containing the red, green, and blue values,
46+
* in that order.
47+
*/
48+
Color.prototype.rgb = function() {
49+
throw new Error('not implemented');
50+
};
51+
52+
/**
53+
* Class representing a color with transparency information.
54+
*
55+
* @class
56+
* @implements {Color}
57+
*/
58+
function TransparentColor() {}
59+
60+
// inherits the documentation from `Color#rgb`
61+
TransparentColor.prototype.rgb = function() {
62+
// ...
63+
};
64+
65+
/**
66+
* Get the color as an array of red, green, blue, and alpha values, represented
67+
* as decimal numbers between 0 and 1.
68+
*
69+
* @returns {Array<number>} An array containing the red, green, blue, and alpha
70+
* values, in that order.
71+
*/
72+
TransparentColor.prototype.rgba = function() {
73+
// ...
74+
};
75+
```
76+
{% endexample %}

‎content/en/tags-interface.md

Lines changed: 90 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,90 @@
1+
---
2+
tag: interface
3+
description: This symbol is an interface that others can implement.
4+
version: '>=3.3.0'
5+
related:
6+
- tags-implements.html
7+
---
8+
9+
## Syntax
10+
11+
With the JSDoc tag dictionary (enabled by default):
12+
13+
`@interface [<name>]`
14+
15+
With the [Closure Compiler][closure] tag dictionary:
16+
17+
`@interface`
18+
19+
[closure]: https://developers.google.com/closure/compiler/docs/js-for-compiler#tags
20+
21+
22+
## Overview
23+
24+
The `@interface` tag marks a symbol as an interface that other symbols can implement. For example,
25+
your code might define a parent class whose methods and properties are stubbed out. You can add the
26+
`@interface` tag to the parent class to indicate that child classes must implement the parent class'
27+
methods and properties.
28+
29+
Add the `@interface` tag to the top-level symbol for the interface (for example, a constructor
30+
function). You do not need to add the `@interface` tag to each member of the interface (for example,
31+
the interface's instance methods).
32+
33+
If you are using the JSDoc tag dictionary (enabled by default), you can also define an interface
34+
with virtual comments, rather than by writing code for the interface. See "[Virtual comments that
35+
define an interface][virtual-comments]" for an example.
36+
37+
[virtual-comments]: #virtual-comments
38+
39+
40+
## Examples
41+
42+
In the following example, the `Color` function represents an interface that other classes can
43+
implement:
44+
45+
{% example "Using the @interface tag" %}
46+
47+
```js
48+
/**
49+
* Interface for classes that represent a color.
50+
*
51+
* @interface
52+
*/
53+
function Color() {}
54+
55+
/**
56+
* Get the color as an array of red, green, and blue values, represented as
57+
* decimal numbers between 0 and 1.
58+
*
59+
* @returns {Array&lt;number>} An array containing the red, green, and blue values,
60+
* in that order.
61+
*/
62+
Color.prototype.rgb = function() {
63+
throw new Error('not implemented');
64+
};
65+
```
66+
{% endexample %}
67+
68+
<a name="virtual-comments"></a>
69+
The following example uses virtual comments, rather than code, to define the `Color` interface:
70+
71+
{% example "Virtual comments that define an interface" %}
72+
73+
```js
74+
/**
75+
* Interface for classes that represent a color.
76+
*
77+
* @interface Color
78+
*/
79+
80+
/**
81+
* Get the color as an array of red, green, and blue values, represented as
82+
* decimal numbers between 0 and 1.
83+
*
84+
* @function
85+
* @name Color#rgb
86+
* @returns {Array&lt;number>} An array containing the red, green, and blue values,
87+
* in that order.
88+
*/
89+
```
90+
{% endexample %}

‎index.html

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -106,12 +106,16 @@ <h2 id="block-tags">Block Tags</h2>
106106
<dd>Document a global object.</dd>
107107
<dt><a href="tags-ignore.html">@ignore</a></dt>
108108
<dd>Omit a symbol from the documentation.</dd>
109+
<dt><a href="tags-implements.html">@implements</a></dt>
110+
<dd>This symbol implements an interface.</dd>
109111
<dt><a href="tags-inheritdoc.html">@inheritdoc</a></dt>
110112
<dd>Indicate that a symbol should inherit its parent&#39;s documentation.</dd>
111113
<dt><a href="tags-inner.html">@inner</a></dt>
112114
<dd>Document an inner object.</dd>
113115
<dt><a href="tags-instance.html">@instance</a></dt>
114116
<dd>Document an instance member.</dd>
117+
<dt><a href="tags-interface.html">@interface</a></dt>
118+
<dd>This symbol is an interface that others can implement.</dd>
115119
<dt><a href="tags-kind.html">@kind</a></dt>
116120
<dd>What kind of symbol is this?</dd>
117121
<dt><a href="tags-lends.html">@lends</a></dt>

‎tags-implements.html

Lines changed: 113 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,113 @@
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="This symbol implements an interface.">
8+
<title>Use JSDoc: @implements</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>@implements</h1>
25+
<h2>Table of Contents</h2>
26+
<ul>
27+
<li>
28+
<a href="#syntax">Syntax</a>
29+
</li>
30+
<li>
31+
<a href="#overview">Overview</a>
32+
</li>
33+
<li>
34+
<a href="#examples">Examples</a>
35+
</li>
36+
<li>
37+
<a href="#related-links">Related Links</a>
38+
</li>
39+
</ul>
40+
<h2 id="syntax">Syntax</h2>
41+
<p><code>@implements {typeExpression}</code>
42+
</p>
43+
<h2 id="overview">Overview</h2>
44+
<p>The <code>@implements</code> tag indicates that a symbol implements an interface.</p>
45+
<p>Add the <code>@implements</code> tag to the top-level symbol that implements the interface (for example, a constructor function). You do not need to add the
46+
<code>@implements</code> tag to each member of the implementation (for example, the implementation&#39;s instance methods).</p>
47+
<p>If you do not document one of the symbols in the implementation, JSDoc will automatically use the interface&#39;s documentation for that symbol.</p>
48+
<h2 id="examples">Examples</h2>
49+
<p>In the following example, the <code>TransparentColor</code> class implements the <code>Color</code> interface and adds a <code>TransparentColor#rgba</code> method.</p>
50+
<figure>
51+
<figcaption>Using the @implements tag</figcaption><pre class="prettyprint lang-js"><code>/**
52+
* Interface for classes that represent a color.
53+
*
54+
* @interface
55+
*/
56+
function Color() {}
57+
58+
/**
59+
* Get the color as an array of red, green, and blue values, represented as
60+
* decimal numbers between 0 and 1.
61+
*
62+
* @returns {Array&lt;number>} An array containing the red, green, and blue values,
63+
* in that order.
64+
*/
65+
Color.prototype.rgb = function() {
66+
throw new Error('not implemented');
67+
};
68+
69+
/**
70+
* Class representing a color with transparency information.
71+
*
72+
* @class
73+
* @implements {Color}
74+
*/
75+
function TransparentColor() {}
76+
77+
// inherits the documentation from `Color#rgb`
78+
TransparentColor.prototype.rgb = function() {
79+
// ...
80+
};
81+
82+
/**
83+
* Get the color as an array of red, green, blue, and alpha values, represented
84+
* as decimal numbers between 0 and 1.
85+
*
86+
* @returns {Array&lt;number>} An array containing the red, green, blue, and alpha
87+
* values, in that order.
88+
*/
89+
TransparentColor.prototype.rgba = function() {
90+
// ...
91+
};
92+
</code></pre>
93+
</figure>
94+
<h2 id="related-links">Related Links</h2>
95+
<p>
96+
<a href="tags-interface.html">@interface</a>
97+
</p>
98+
</article>
99+
<footer>
100+
<a class="license-badge" href="http://creativecommons.org/licenses/by-sa/3.0/">
101+
<img alt="Creative Commons License" class="license-badge" src="images/cc-by-sa.svg" width="80" height="15" />
102+
</a>
103+
<br> Copyright &#169; 2011-2014 the
104+
<a href="https://github.com/jsdoc3/jsdoc3.github.com/contributors">contributors</a> to the JSDoc 3 documentation project.
105+
<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/">
106+
Creative Commons Attribution-ShareAlike 3.0 Unported License</a>.
107+
</footer>
108+
<script type="text/javascript">
109+
prettyPrint();
110+
</script>
111+
</body>
112+
113+
</html>

0 commit comments

Comments
 (0)
0