@event JSDoc keyword is not emit event documentation

[alexprey]

https://jsdoc.app/tags-event.html

The following comment must provide description for event and provide class of event

/**
 * The `close` event fired when user click to X button in the panel.
 * @event CloseEventArgs#close
 */

Markup documentation also must be valid for events

<!--
    The `close` event fired when user click to X button in the panel.
    @event CloseEventArgs#close
-->
<button type="button" on:click={() => dispatch('close')}>&times;</button>

[ekhaled]

@alexprey did not want to open another issue regarding this:

How to document multiple forwarded events?

For example:

<!--
      @event focus - fires when focus changes
      @event change - fires when value changes
-->
<input on:focus on:change />

this does not seem to work.

I'm not sure what the preferred way of documenting these is. If there is no preferred way yet, maybe I can have a look at trying to implement the above format

[alexprey]

Hi @ekhaled, That is a good question, because JSDoc is not provide clear description about that. Actually each event description should be a separate comment group. For your example that should be:

<script>
/**
 * Fires when focus changes
 * @event focus
 */
/**
 * Fires when value changes
 * @event change
 */
</script>

<input on:focus on:change />

or in HTML:

<!--
      fires when focus changes
      @event focus
-->
<!--
      Fires when value changes
      @event change
-->
<input on:focus on:change />

[ekhaled]

I think on the js side, we have it quite covered. We can just do:

import { createEventDispatcher } from "svelte";
let fire = createEventDispatcher();

/**
 * fires something
 * */
fire("something");

/**
 * fires something2
 * */
fire("something2");

and it works pretty well.

It's the HTML side thats causing problems.

We can use multiple comment groups, but then it introduces a line-break between each block, which might not be ideal (for example display:inline elements are whitespace sensitive).

Also in terms of parsing, we might have trouble trying to figure out how far up the template we should go to ensure we have all comment blocks.

[alexprey]

Actually, the most popular style of documentation writing of component/class behaviour that putting whole description at the top. So, for your case I think that it's OK if you profile documentation about markup fired events at the top of the component, as I provide at the first example of previous comment. And I support that support parsing of @event keyword in HTML comments is not important