@event: multiple entries in TOC
AdrianVasiliu opened this issue · comments
When documenting events using the syntax specified at http://usejsdoc.org/tags-event.html - say, @event module:mymodule#my-event -, the TOC of the generated doc potentially includes mutliple entries for the same event: one for each subclass of the class which declares the event. This has the following drawbacks:
- For projects with many direct and indirect subclasses of the classes which emit events, the TOC gets overhelmed by the number of TOC entries for the same event (which only differ by their pointed URL).
- The links for events in the TOC correctly point to the event in the doc of the class which emits them, however for all occurrences of the event corresponding to subclasses of the class which actually emits the event, the link opens the doc of the superclass in its default "Hide inherited" mode, thus the Event section is not visible.
How to reproduce:
Use the modified test cases in PR #42 to reproduce the issue => in the TOC, event-foo appears twice (it would appear 10 times if there would be 9 subclasses of the class which declares the event):
The issue actually affects the doc of https://github.com/ibm-js/delite.
This issue seems to be the same as jsdoc/jsdoc#488 .
Remark: the workaround suggested here: jsdoc/jsdoc#488 (comment), that is using @event module:mymodule.my-event instead of @event module:mymodule#my-event does the trick for avoiding the duplicated entries. But it has the unnecceptable drawback that they are no longer inherited by subclasses of the class which emits (and declares) them.
jsdoc/jsdoc#488 (comment) says it will be fixed (no ETA). Not sure if jsdoc-amddcl could fix on its side.