Support event params (detail)

[kcmr]

First of all, thank you for your tool!

When using CustomEvent we need to document the detail as well as its type and the type of each of the properties of the detail when an object is used. This is possible using JSDocs with the @param flag and it would be great to have this feature for the @fires flag.

[runem]

Hi, thanks for reporting this. I think I will need an example of how the @param JSDoc tag can be used to document the properties of detail. Right now you can also use this syntax this in order to document the type of your event:

@fires {CustomEvent<string>} change - Dispatched when the text of the text field changes
@fires {CustomEvent<{text: string, createdAt: Date}>} new-comment - Dispatched when a new comment is added

See example here

[kcmr]

Hi, thank you for the example. I didn't know that.

Regarding to how to document event params, this is how it was done using Polymer Analyzer: https://polymer-library.polymer-project.org/2.0/docs/tools/documentation#events

/**
 * Fired when `element` changes its awesomeness level.
 *
 * @event awesome-change
 * @param {number} newAwesome New level of awesomeness.
 */

I noticed that @event flag also works to document events, but the params are not taken into account.

And thank you for such a great tool :)

[x3igh7]

Hi @runem - will types be analyzed from the code?

Say I have something like this in Typescript:

myDispatchMethod() {
 this.dispatchEvent(new CustomEvent<string>())
}

Will analyze generate the "detailType" property in custom-elements.json?