Support slots, events and external .js

[kolesoffac]

Do you plan to add support for support slots, events, mixins and external .js?

my .vue:

<template>
.....
</template>

<script src="./my.js"><script>

[Kocal]

Hello,

Nope I didn't plan anything, but this can be nice to have slots and events with @vue-slot my-slot-name Description....

For mixins, do you think to a particular behavior?

• will it be configurable with @vue-mixin MyMixin?
• should a link for this mixin be displayed on generated documentation?

For external .js files, I don't see why it should be useful to have them. 🤔

[kolesoffac]

For external .js files, I don't see why it should be useful to have them.

To dont dificult temlate, to .vue was max clear and contains only template.

This bad?

[kolesoffac]

should a link for this mixin be displayed on generated documentation?

This main aimp!

[Kocal]

Mmmh, okay.

I understand what you are saying, and yes those are interesting functionalities (but not really for external .js files 🤔).

@vue-slot and @vue-event will be easy to implement, @vue-mixin will be a little harder 🤔

Feel free to open a pull request, thanks! 🙂

[kolesoffac]

... but not really for external .js files 🤔 ...

Why? What is the reason?

[Kocal]

Firstly, I think it's counter-productive to split a .vue in multiple files (.vue for template, a .js for javascript, and maybe a .css for your styles).
If your JavaScript code directly acts on your template, then it should be kept inside your .vue in my opinion.

Secondly, this is not how JSDoc works (I think?).
Yes we can dev something to inject your .js on-the-fly, then it will be able to be parsed and a documentation will be generated, but it's dirty and will result into some weird behaviors. 😞

[kolesoffac]

In such cases, how will myxins belong to this component? Mixins are precisely defined in separate files.

[kolesoffac]

... counter-productive

https://vuejs.org/v2/guide/single-file-components.html#What-About-Separation-of-Concerns

[Kocal]

Thank you, I know this feature exists, that why I said "I think".

For mixins, you should use @vue-mixin Foo I guess.

[kolesoffac]

I also use computed and data selection in mixin, but all definitions

 /**
   * @vue-prop {Number} initialCounter - Initial counter's value
   * @vue-prop {Number} [step=1] - Step
   * @vue-data {Number} counter - Current counter's value
   * @vue-computed {String} message
   */

are located in .vue.

How to deal with these fields?

[Kocal]

Mmmh...

Good question. Maybe @vue-mixin can take a filename that will be read and parsed by jsdoc-vuejs?
And then after parsing, we populate component's prop/data/computed?

What do you think?

[Akaryatrh]

@kolesoffac Did you find a solution when using external files? Or did you switch to another solution?

[pbastowski]

Hi guys

Both slots (scoped) and events have an ability to pass parameters. It would be great if we had a @vue-slot and @vue-event annotation, which would allow us to follow it with @param annotations. @params would then describe the slots and events for us. The result would be a table for slots and a separate table for events, just like we get for @vue-prop.

For example

/**
 * The s-popup component displays a popup window with your text and an optional title.
 * 
 * @vue-slot activator Clicking this content will display the popup
 * @param {object} item This is purely fictional, just to demonstrate how the @param would be used
 *
 * @vue-slot [title] An optional popup title
 * @vue-slot default The content to be displayed
 *
 * @vue-event close
 * @param {string} result The button that the user clicked (OK or Cancel)
 * 

Is this feasible?

[Kocal]

I don't think this is feasible, because in JSDoc core, when you have one comment block, @param will apply for the whole comment block.

[pbastowski]

I see.
Well then @vue-slot and @vue-event, even without @param, will still be much better then nothing at all :)

And I can use separate @typedef blocks to define the parameters and then refer to them in the slot/event descriptions.

[pbastowski]

Update: @event can be used to document events already, like this

/**
 * Toggle flag that displays this list
 * @event toggle-show-list
 * @property val
 */

/**
 * Emits event to the parent to remove the given UUID
 * @event remove-delegate
 * @property {uuid} UUID
 */

/**
 * Tell the parent to close the delegate form
 * @event close-delegate-form
 */

[Elaniobro]

@Kocal did you ever get around to building out the @vue-slot? I see this issue is still opened.
@pbastowski did you ever get it working?

[Kocal]

@Elaniobro hi, no I didn't work on it, but you are free to send a PR if you need it.

[pbastowski]

@Elaniobro Sorry, I don’t remember exactly what I did with that. It’s been almost two years since then.

[DaveTorrey]

@Kocal have you seen vuese? It works really well for documenting vue components. Personally the only reason I've avoided using it is because it seems to be specific to vue and I don't think integrates the rest of jsdocs like your plugin does. But it might provide ideas for implementation