jsdoc: Problem with inherited event definitions - do appear twice
Lets say I have 2 AMD modules, with “modules/B” inheriting from “modules/A”. In addition, “modules/A” has an event definition, for a custom event “belonging” to this module, defined like this:
/**
* This is a utility class.
* @class MyClass
*/
var myClass = function() {};
define("modules/A", ["myClass"], function (myClass) {
/**
* Event definition, event "belongs" to Module A
* @event module:modules/A#customEvent
*/
/**
* My Superclass module
* @module modules/A
*/
var A = myClass(/** @lends module:modules/A.prototype */ {
/**
* Use this to make a module:modules/A
* @constructs
*/
constructor: function () { }
});
return A;
});
In “modules/B”, there is no such Event definition:
define("modules/B", ["myClass", "modules/A"], function (myClass, moduleA) {
/**
* My Subclass module
* @module modules/B
* @extends module:modules/A
* @requires module:modules/A
*/
var B = myClass(moduleA, /** @lends module:modules/B.prototype */ {
/**
* Use this to make a module:modules/B
* @constructs
* @extends module:modules/A
*/
constructor: function () { }
});
return B;
});
The event is stil being displayed in the resulting docs, marked as “inherited from modules/A”. So far so good. But what bugs me that now, in the global “events” section, this event is displayed twice. (And if I use more Subclasses, an entry gets added for each of these)
Since this event is essentially the same thing fromthe same source, I think this is a bug, I would expect that this event would be only displayed once in the “events” section.
About this issue
- Original URL
- State: open
- Created 11 years ago
- Comments: 15 (6 by maintainers)
OK, that’s good to hear. Meanwhile I have found a sort of workaround, so if I define the event as static member:
@event module:mvvm/Model.model/:cid/statusinstead of:@event module:mvvm/Model#model/:cid/statusthe events are not duplicated in the resulting docs.Yes, I think so, at least if the docs in the Superclass are not overidden. And I would extend it also to consuming (ie @listens), not firing only.
Depends on what it fires? I’d say the following rule could make sense for displaying the event in the “Event” Section: “If two defined events have the same identifier, do not duplicate the entries in the events section, but include docs (with pointers to the inherited event definition) for the actual module / class page”. Just as it works with modules right now (would implement the same behavior with classes, too)
With “identifer”, I mean this: @event module:mvvm/Model#model/status
So, if two modules are firing / listening an event named “module:mvvm/Model#model/status”, I would see that as an identical event that should not be duplicated in the events section.
I would extend that also to @listens. With my current scheme, I define an event either as:
a) “global”, esp when the event is used by several classes / modules, and cannot be clearly assigned to just one module / class b) “belonging to a module” - if that event is only (or at least mainly) used by a certain class / module. And I look rather for the act of consuming events, not firing, but of course you could see it the other way around. Think both approaches are valid from my POV.
So the whole point - for me - for defining an event attached to a class/module is to highlight the fact that the module is in a way tied to a specific event.
What I assume, though is that an event with the same identifier is the same event. But really, anything else wouldn’t make too much sense?
@event definition in the subclass? But again, redefining the same event is not what I would do at all. Maybe that would make sense if I have an event, that is somewhat extended (eg additional params) in the subclass, but personally I do not have such a case (yet).
I looked into this again. It appears that JSDoc’s current behavior varies depending on whether the event is attached to a module or a class.
Suppose you have a bass class (or module) A and a derived class (or module) B. Here’s what happens right now:
This is kind of silly. And after looking at this more closely, I agree with you that we shouldn’t show the same event over and over in the navbar.
But I also want to think about the right way to deal with inherited events in the docs for each class/module. A few of the questions I have in mind:
@firestag?I may use this issue to make the behavior consistent and slim down the navbar, then file a separate issue to follow up on these other questions. For now, just reopening this issue.