Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

@event JSDoc keyword is not emit event documentation #30

Open
alexprey opened this issue Aug 20, 2020 · 4 comments
Open

@event JSDoc keyword is not emit event documentation #30

alexprey opened this issue Aug 20, 2020 · 4 comments
Labels
enhancement New feature or request

Comments

@alexprey
Copy link
Collaborator

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
Copy link
Contributor

ekhaled commented Sep 1, 2021

@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
Copy link
Collaborator Author

alexprey commented Sep 1, 2021

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
Copy link
Contributor

ekhaled commented Sep 1, 2021

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
Copy link
Collaborator Author

alexprey commented Sep 1, 2021

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

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
enhancement New feature or request
Projects
None yet
Development

No branches or pull requests

2 participants