How to use JSDoc to document a Vue component with script setup?

Question

I'm building a Vue library with TypeScript. I'd like to export the documentation of the components, like I do with ordinary functions.

Previously we would do this:

<script>
/**
 * This is the documentation of my component.
 */
export default {
}
</script>

<template></template>

But now with script setup:

<script setup lang="ts">
</script>

<template></template>

How do we document the component?

Answer 1

I don't have the reputation to comment on https://stackoverflow.com/a/72003725/18059097 or I would, but it seems you don't even need to put anything in the default export, so you can simply do

<script>
/**
 * This is my well documented component
 */
export default {};
</script>
<script setup>
// your code
</script

Using this style can also be advantageous so that you have a way to use the editor's Go To References feature, though it's a bit of a silly workaround.

Another slightly different idea is to create a separate file index.js and do

import { default as MyComponentVue } from './MyComponent.vue';

/**
 * This is my well documented component.
 */
export const MyComponent = MyComponentVue;

This of course has the downside of the documentation being in a separate file though.

Answer 2

With <script setup> you can't use JSDoc on the component export.

It's a compiler syntaxic sugar that gets out the export of the setup function, so you obviously can't comment a function that is "generated" by the compiler.

If you really needs JSDoc, you should use a regular <script> with a default export :)

<script>
/** This is my nice component documentation */
export default {
  name: 'MyComponent',
  setup() {
    // your code
  }, 
}
</script>

Also works with the typescript defineComponent wrapper:

<script>
import { defineComponent } from 'vue'

/** This is my nice component documentation */
export default defineComponent({
  name: 'MyComponent',
  setup() {
    // your code
  }
})
</script>

EDIT: as mentionned by @EstusFlask in the comments, you can mix both <script setup> and <script> on a SFC component (see docs) So you can use the regular script to expose your JSDoc.

<script setup>
// component setup. Takes priority over the eventual `setup()` function of the export object in <script>.
</script>

<script>
/** This is my nice component documentation */
export default {
  name: 'MyComponent',
}
</script>