Skip to content

Commit f7b9352

Browse files
hegemonichegemonic
committed
document the listens tag (#25)
1 parent d899ef3 commit f7b9352

File tree

7 files changed

+228
-118
lines changed

7 files changed

+228
-118
lines changed

‎content/en/tags-event.md

Lines changed: 3 additions & 58 deletions
Original file line numberDiff line numberDiff line change
@@ -3,6 +3,7 @@ tag: event
33
description: Document an event.
44
related:
55
- tags-fires.html
6+
- tags-listens.html
67
---
78

89
## Syntax
@@ -16,7 +17,8 @@ The @event tag allows you to document an event that can be fired. A typical even
1617
an object with a defined set of properties.
1718

1819
Once you have used the @event tag to define a specific type of event, you can use the @fires tag to
19-
indicate that a method can fire that event.
20+
indicate that a method can fire that event. You can also use the @listens tag to indicate that a
21+
symbol listens for the event.
2022

2123
JSDoc automatically prepends the namespace `event:` to each event's name. In general, you must
2224
include this namespace when you link to the event in another doclet. (The @fires tag is a notable
@@ -76,60 +78,3 @@ Hurl.prototype.snowball = function() {
7678
*/
7779
```
7880
{% endexample %}
79-
80-
The following example shows how to document events in the context of AMD modules.
81-
82-
{% example "Documenting events in AMD modules" %}
83-
84-
```js
85-
define('playground/monitor', [], function () {
86-
/**
87-
* Keeps an eye out for snowball-throwers.
88-
*
89-
* @module playground/monitor
90-
*/
91-
var exports = {
92-
/**
93-
* Report the throwing of a snowball.
94-
*
95-
* @method
96-
* @param {module:hurler#event:snowball} e - A snowball event.
97-
* @listens module:hurler#snowball
98-
*/
99-
reportThrowage: function (e) {
100-
this.log('snowball thrown: velocity ' + e.velocity);
101-
}
102-
};
103-
104-
return exports;
105-
});
106-
107-
define('hurler', [], function () {
108-
/**
109-
* Event reporting that a snowball has been hurled.
110-
*
111-
* @event module:hurler#snowball
112-
* @property {number} velocity - The snowball's velocity, in meters per second.
113-
*/
114-
115-
/**
116-
* Snowball-hurling module.
117-
*
118-
* @module hurler
119-
*/
120-
var exports = {
121-
/**
122-
* Attack an innocent (or guilty) person with a snowball.
123-
*
124-
* @method
125-
* @fires module:hurler#snowball
126-
*/
127-
attack: function () {
128-
this.emit('snowball', { velocity: 10 });
129-
}
130-
};
131-
132-
return exports;
133-
});
134-
```
135-
{% endexample %}

‎content/en/tags-fires.md

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -5,6 +5,7 @@ synonyms:
55
- emits
66
related:
77
- tags-event.html
8+
- tags-listens.html
89
---
910

1011
## Syntax

‎content/en/tags-listens.md

Lines changed: 80 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,80 @@
1+
---
2+
tag: listens
3+
description: List the events that a symbol listens for.
4+
related:
5+
- tags-event.html
6+
- tags-fires.html
7+
---
8+
9+
## Syntax
10+
11+
`@listens <eventName>`
12+
13+
14+
## Overview
15+
16+
The `@listens` tag indicates that a symbol listens for the specified event. Use the
17+
[`@event tag`][event-tag] to document the event's content.
18+
19+
[event-tag]: tags-event.html
20+
21+
22+
## Example
23+
24+
The following example shows how to document an event named `module:hurler~event:snowball`, as well
25+
as a method named `module:playground/monitor.reportThrowage` that listens for the event.
26+
27+
{% example "Documenting an event and its listener" %}
28+
29+
```js
30+
define('hurler', [], function () {
31+
/**
32+
* Event reporting that a snowball has been hurled.
33+
*
34+
* @event module:hurler~snowball
35+
* @property {number} velocity - The snowball's velocity, in meters per second.
36+
*/
37+
38+
/**
39+
* Snowball-hurling module.
40+
*
41+
* @module hurler
42+
*/
43+
var exports = {
44+
/**
45+
* Attack an innocent (or guilty) person with a snowball.
46+
*
47+
* @method
48+
* @fires module:hurler~snowball
49+
*/
50+
attack: function () {
51+
this.emit('snowball', { velocity: 10 });
52+
}
53+
};
54+
55+
return exports;
56+
});
57+
58+
define('playground/monitor', [], function () {
59+
/**
60+
* Keeps an eye out for snowball-throwers.
61+
*
62+
* @module playground/monitor
63+
*/
64+
var exports = {
65+
/**
66+
* Report the throwing of a snowball.
67+
*
68+
* @method
69+
* @param {module:hurler~event:snowball} e - A snowball event.
70+
* @listens module:hurler~event:snowball
71+
*/
72+
reportThrowage: function (e) {
73+
this.log('snowball thrown: velocity ' + e.velocity);
74+
}
75+
};
76+
77+
return exports;
78+
});
79+
```
80+
{% endexample %}

‎index.html

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -125,6 +125,8 @@ <h2 id="tag-dictionary">Tag Dictionary</h2>
125125
<dd>Identify the license that applies to this code.</dd>
126126
<dt><a href="tags-link.html">@link</a></dt>
127127
<dd>Inline tag - create a link.</dd>
128+
<dt><a href="tags-listens.html">@listens</a></dt>
129+
<dd>List the events that a symbol listens for.</dd>
128130
<dt><a href="tags-member.html">@member</a> (synonyms: @var)</dt>
129131
<dd>Document a member.</dd>
130132
<dt><a href="tags-memberof.html">@memberof</a></dt>

‎tags-event.html

Lines changed: 10 additions & 57 deletions
Original file line numberDiff line numberDiff line change
@@ -42,7 +42,8 @@ <h2 id="syntax">Syntax</h2>
4242
</p>
4343
<h2 id="overview">Overview</h2>
4444
<p>The @event tag allows you to document an event that can be fired. A typical event is represented by an object with a defined set of properties.</p>
45-
<p>Once you have used the @event tag to define a specific type of event, you can use the @fires tag to indicate that a method can fire that event.</p>
45+
<p>Once you have used the @event tag to define a specific type of event, you can use the @fires tag to indicate that a method can fire that event. You can also
46+
use the @listens tag to indicate that a symbol listens for the event.</p>
4647
<p>JSDoc automatically prepends the namespace <code>event:</code> to each event&#39;s name. In general, you must include this namespace when you link to the event
4748
in another doclet. (The @fires tag is a notable exception; it allows you to omit the namespace.)</p>
4849
<p><strong>Note</strong>: JSDoc 3 uses @event doclets to document the content of an event. In contrast, JSDoc Toolkit 2 used @event doclets to identify a function
@@ -87,65 +88,17 @@ <h2 id="examples">Examples</h2>
8788
* @type {object}
8889
* @property {boolean} isPacked - Indicates whether the snowball is tightly packed.
8990
*/
90-
</code></pre>
91-
</figure>
92-
<p>The following example shows how to document events in the context of AMD modules.</p>
93-
<figure>
94-
<figcaption>Documenting events in AMD modules</figcaption><pre class="prettyprint lang-js"><code>define('playground/monitor', [], function () {
95-
/**
96-
* Keeps an eye out for snowball-throwers.
97-
*
98-
* @module playground/monitor
99-
*/
100-
var exports = {
101-
/**
102-
* Report the throwing of a snowball.
103-
*
104-
* @method
105-
* @param {module:hurler#event:snowball} e - A snowball event.
106-
* @listens module:hurler#snowball
107-
*/
108-
reportThrowage: function (e) {
109-
this.log('snowball thrown: velocity ' + e.velocity);
110-
}
111-
};
112-
113-
return exports;
114-
});
115-
116-
define('hurler', [], function () {
117-
/**
118-
* Event reporting that a snowball has been hurled.
119-
*
120-
* @event module:hurler#snowball
121-
* @property {number} velocity - The snowball's velocity, in meters per second.
122-
*/
123-
124-
/**
125-
* Snowball-hurling module.
126-
*
127-
* @module hurler
128-
*/
129-
var exports = {
130-
/**
131-
* Attack an innocent (or guilty) person with a snowball.
132-
*
133-
* @method
134-
* @fires module:hurler#snowball
135-
*/
136-
attack: function () {
137-
this.emit('snowball', { velocity: 10 });
138-
}
139-
};
140-
141-
return exports;
142-
});
14391
</code></pre>
14492
</figure>
14593
<h2 id="related-links">Related Links</h2>
146-
<p>
147-
<a href="tags-fires.html">@fires</a>
148-
</p>
94+
<ul>
95+
<li>
96+
<a href="tags-fires.html">@fires</a>
97+
</li>
98+
<li>
99+
<a href="tags-listens.html">@listens</a>
100+
</li>
101+
</ul>
149102
</article>
150103
<footer>
151104
<a class="license-badge" href="http://creativecommons.org/licenses/by-sa/3.0/">

‎tags-fires.html

Lines changed: 8 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -63,9 +63,14 @@ <h2 id="examples">Examples</h2>
6363
</code></pre>
6464
</figure>
6565
<h2 id="related-links">Related Links</h2>
66-
<p>
67-
<a href="tags-event.html">@event</a>
68-
</p>
66+
<ul>
67+
<li>
68+
<a href="tags-event.html">@event</a>
69+
</li>
70+
<li>
71+
<a href="tags-listens.html">@listens</a>
72+
</li>
73+
</ul>
6974
</article>
7075
<footer>
7176
<a class="license-badge" href="http://creativecommons.org/licenses/by-sa/3.0/">

0 commit comments

Comments
 (0)