@fires and @events
Arcanis
I'm trying to generate a doc for a code using events, but I don't
really understand how to do.
Minimal code :
https://gist.github.com/36c06a928796a139884d
I expect to see a link in the 'fires' section on the function to
foo.html#event:snowball, and an entry named 'snowball' in the class
'Events' section.
Instead, I don't see anything except the long name of the event fired.
I've tried to set the long name in the @event tag
('foo#event:snowball'), but no link, and the entry in 'Events' is
called 'event:snowball' instead of 'snowball'. I've also tried to set
the @event tag to 'foo#snowball', but no link (and it does not seems
to be a correct way to do, according to http://code.google.com/p/jsdoc-toolkit/wiki/TagEvent).
Am I doing something wrong ?
Thanks,
(I'm using JSDoc 3)
Michael Mathews
There are a combination of issues appearing in your example. Firstly there is a missing feature in JSDoc 3, where the events marked with the @fire tag weren't being linked to. The fix is already in the repo, but no matter what you wrote in your docs it wouldn't have been linked to before that fix -- sorry about that :)
https://github.com/micmath/jsdoc/commit/18d147281075a5da9d02406aff9d2ce67a81cb16#diff-1
Second issue is with your "@event snowball" tag. There are two problems: firstly the word "snowball" there is saying "my event is named snowball, that's how you should refer to it." Then in your @fires tag you refer to it as "foo#event:snowball". You might expect that you should change the tag to "@event foo#event:snowball", but that brings us to the third issue... It may be confusing I admit, but when you give the name of the thing you are documenting along with the "kind tag", like @event (or @class, or @method, or whatever), you've already said it's an @event and you don't have to repeat the "event:" in the name itself. So the actual correct tag there would be "@event foo#snowball".
Here's the working version (after you pull the latest JSDoc 3 from github):
````javascript
/**
* @class foo
*/
var foo = function () {
};
/**
* Does something.
*
* @fires foo#event:snowball
* @fires foo#event:brick
*/
foo.prototype.bar = function () {
/**
* @event foo#snowball
*/
this.emit('snowball', {});
/**
* @event foo#brick
*/
this.emit('brick', {});
};
````
--
Michael Mathews
mic...@gmail.com
> --
> You received this message because you are subscribed to the Google Groups "JSDoc Users" group.
> To post to this group, send email to jsdoc...@googlegroups.com.
> To unsubscribe from this group, send email to jsdoc-users...@googlegroups.com.
> For more options, visit this group at http://groups.google.com/group/jsdoc-users?hl=en.
>
Arcanis
the pull !
However, with : https://gist.github.com/ffb1b5829f26ca6b4936, I've got
another little problem with the links : as you can see, each method
have an event of the same name. But the @fires link points to the
method, and not the event (even with the 'event:' prefix).
And a suggestion : if @event allow to omit to write the 'event:'
prefix, shouldn't @fires do the same ?
On Oct 2, 11:32 pm, Michael Mathews <micm...@gmail.com> wrote:
> Hello,
>
> There are a combination of issues appearing in your example. Firstly there is a missing feature in JSDoc 3, where the events marked with the @fire tag weren't being linked to. The fix is already in the repo, but no matter what you wrote in your docs it wouldn't have been linked to before that fix -- sorry about that :)
>
> Second issue is with your "@event snowball" tag. There are two problems: firstly the word "snowball" there is saying "my event is named snowball, that's how you should refer to it." Then in your @fires tag you refer to it as "foo#event:snowball". You might expect that you should change the tag to "@event foo#event:snowball", but that brings us to the third issue... It may be confusing I admit, but when you give the name of the thing you are documenting along with the "kind tag", like @event (or @class, or @method, or whatever), you've already said it's an @event and you don't have to repeat the "event:" in the name itself. So the actual correct tag there would be "@event foo#snowball".
>
> Here's the working version (after you pull the latest JSDoc 3 from github):
>
> ````javascript
> /**
> * @class foo
> */
>
> var foo = function () {
>
> };
>
> /**
> * Does something.
> *
> * @fires foo#event:snowball
> * @fires foo#event:brick
> */
>
> foo.prototype.bar = function () {
>
> /**
> * @event foo#snowball
> */
> this.emit('snowball', {});
>
> /**
> * @event foo#brick
> */
> this.emit('brick', {});};
>
> ````
>
> --
> Michael Mathews
> On 2 Oct 2011, at 20:10, Arcanis wrote:
>
>
>
>
>
>
>
> > Hello,
>
> > I'm trying to generate a doc for a code using events, but I don't
> > really understand how to do.
>
> > Minimal code :
> >https://gist.github.com/36c06a928796a139884d
>
> > I expect to see a link in the 'fires' section on the function to
> > foo.html#event:snowball, and an entry named 'snowball' in the class
> > 'Events' section.
> > Instead, I don't see anything except the long name of the event fired.
>
> > I've tried to set the long name in the @event tag
> > ('foo#event:snowball'), but no link, and the entry in 'Events' is
> > called 'event:snowball' instead of 'snowball'. I've also tried to set
> > the @event tag to 'foo#snowball', but no link (and it does not seems
Michael Mathews
On 2 Oct 2011, at 23:00, Arcanis wrote:
> Thanks, it works for the @event problem, and almost for the link, with
> the pull !
>
> However, with : https://gist.github.com/ffb1b5829f26ca6b4936, I've got
> another little problem with the links : as you can see, each method
> have an event of the same name. But the @fires link points to the
> method, and not the event (even with the 'event:' prefix).
That looks like a bug in the way links are generated. If you create a ticket on the github issue tracker I will look into it and post a fix sometime this week.
>
> And a suggestion : if @event allow to omit to write the 'event:'
> prefix, shouldn't @fires do the same ?
The only problem I can see with that is that it becomes a "lossy" operation. By that I mean there is no information lost when the "event:" is _removed_ from `@event foo#event:bar` to become `@event foo#bar`. But, considering that you may want to document that something fires a built-in event, like `click`, then there would be a loss of information if JSDoc always _added_ an "event:" back in. For example, if you had your own "dom.event:click" defined but you wanted to document that a native "dom.click" event were fired, there would be no way to distinguish between the two after JSDoc normalised them both to be "dom.event:click".
Arcanis
> On 2 Oct 2011, at 23:00, Arcanis wrote:
>
> > Thanks, it works for the @event problem, and almost for the link, with
> > the pull !
>
> > However, with :https://gist.github.com/ffb1b5829f26ca6b4936, I've got
> > another little problem with the links : as you can see, each method
> > have an event of the same name. But the @fires link points to the
> > method, and not the event (even with the 'event:' prefix).
>
> That looks like a bug in the way links are generated. If you create a ticket on the github issue tracker I will look into it and post a fix sometime this week.
>
> > And a suggestion : if @event allow to omit to write the 'event:'
> > prefix, shouldn't @fires do the same ?
>
> The only problem I can see with that is that it becomes a "lossy" operation. By that I mean there is no information lost when the "event:" is _removed_ from `@event foo#event:bar` to become `@event foo#bar`. But, considering that you may want to document that something fires a built-in event, like `click`, then there would be a loss of information if JSDoc always _added_ an "event:" back in. For example, if you had your own "dom.event:click" defined but you wanted to document that a native "dom.click" event were fired, there would be no way to distinguish between the two after JSDoc normalised them both to be "dom.event:click".
>
>
named 'click', if I write @fires foo#click, How to know if I talk
about the method or the builtin event ?
Furthermore, multiple event type (customs - builtins) means multiples
APIs. It's not very safe to mix them inside the same tag, if the only
difference between them is the presence of an 'event:' in the middle
of the path.
Michael Mathews
Michael Mathews
mic...@gmail.com
On 3 Oct 2011, at 07:14, Arcanis wrote:
> On Oct 3, 12:24 am, Michael Mathews <micm...@gmail.com> wrote:
>> On 2 Oct 2011, at 23:00, Arcanis wrote:
>>
>>> Thanks, it works for the @event problem, and almost for the link, with
>>> the pull !
>>
>>> However, with :https://gist.github.com/ffb1b5829f26ca6b4936, I've got
>>> another little problem with the links : as you can see, each method
>>> have an event of the same name. But the @fires link points to the
>>> method, and not the event (even with the 'event:' prefix).
>>
>> That looks like a bug in the way links are generated. If you create a ticket on the github issue tracker I will look into it and post a fix sometime this week.
>>
>
> I've opened a ticket : https://github.com/micmath/jsdoc/issues/38
>
>>> And a suggestion : if @event allow to omit to write the 'event:'
>>> prefix, shouldn't @fires do the same ?
>>
>> The only problem I can see with that is that it becomes a "lossy" operation. By that I mean there is no information lost when the "event:" is _removed_ from `@event foo#event:bar` to become `@event foo#bar`. But, considering that you may want to document that something fires a built-in event, like `click`, then there would be a loss of information if JSDoc always _added_ an "event:" back in. For example, if you had your own "dom.event:click" defined but you wanted to document that a native "dom.click" event were fired, there would be no way to distinguish between the two after JSDoc normalised them both to be "dom.event:click".
>>
>>
>
> Assuming a class with a method, a custom event and a builtin event
> named 'click', if I write @fires foo#click, How to know if I talk
> about the method or the builtin event ?
>
> Furthermore, multiple event type (customs - builtins) means multiples
> APIs. It's not very safe to mix them inside the same tag, if the only
> difference between them is the presence of an 'event:' in the middle
> of the path.
Methods can't be fired, so if you write `@fires foo#click` it's safe to assume you don't mean any method with that name. And I think it's normal to assume that JavaScript developers will always be dealing with some combination of the browser's API and their own library's API.
But to be honest I haven't given a lot of deep thought to the idea that `@fires foo#click` should assume `@fires foo#event:click`. If you create a feature request ticket for this I will give it a try at least and see how it works.