/wiki/TagEvent.wiki

 1#summary @event
 2
 3This tag is available as of release 2.1.
 4
 5== The @event Tag ==
 6
 7The `@event` tag allows you to document a function that can be fired when an event of the same name occurs.
 8
 9=== Syntax ===
10
11{{{
12@event
13}}}
14  * The syntax of this tag is identical to the @function tag.
15
16=== Example ===
17
18You can simply tag a normal function as being an event.
19
20{{{
21/**
22 * @event
23 * @param {Boolean} clockwise
24 */
25Cocktail.prototype.stir = function(clockwise) {
26}
27}}}
28
29Or, you can use a named doclet without refering to any function in your code.
30
31{{{
32/**
33 * @name Cocktail#shake
34 * @event
35 * @param {MyEventObject} e
36 * @param {Boolean} [e.withIce=false]
37 */
38}}}
39
40
41=== Referring to Events ===
42
43Note that, by using the named doclet method illustrated above, it is possible to have a method and an event that both have the same name. In order to disambiguate which symbol you are referring to (either the method or the event) the namepath of the event has a prefix of "event:" inserted into it.
44
45So when you need to refer to an event by it's namepath the name should be written as event:name.
46
47{{{
48/**
49 * @constructor
50 * @borrows Cocktail#event:shake as this.event:shake
51 */
52function MilkShake() {
53}
54}}}
55
56=== See Also ===
57  * The [TagFunction @function] tag.
58  * NamePaths