typescript - Hvordan bruke JSDoc for å dokumentere en Vue-komponent med script setup?

Jeg bygger et Vue-bibliotek med TypeScript. Jeg vil gjerne eksportere dokumentasjonen til komponentene, slik jeg gjør med vanlige funksjoner.

Tidligere ville vi gjøre dette:

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

<template></template>

Men nå med script setup:

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

<template></template>

Hvordan dokumenterer vi komponenten?

Svar #1

Med <script setup> kan du ikke bruke JSDoc på komponenteeksporten.

Det er en kompilator syntaktisk sukker som henter ut eksporten av setup-funksjonen, så du kan åpenbart ikke kommentere en funksjon som er "generert" av kompilatoren.

Hvis du virkelig trenger JSDoc, bør du bruke en vanlig <script> med en standard eksport :)

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

Fungerer også med TypeScript-defineComponent-wrapperen:

<script>
import { defineComponent } from 'vue'

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

REDIGER: som nevnt av @EstusFlask i kommentarene, kan du blande både <script setup> og <script> i en SFC-komponent (se dokumentasjonen). Så du kan bruke det vanlige skriptet for å eksponere din 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>

Svar #2

Jeg har ikke ryktet til å kommentere på https://stackoverflow.com/a/72003725/18059097 ellers ville jeg gjort det, men det ser ut til at du ikke engang trenger å legge noe i standardeksporten, så du kan enkelt gjøre

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

Å bruke denne stilen kan også være fordelaktig slik at du har en måte å bruke redaktørens Gå til referanser-funksjon på, selv om det er en litt tåpelig løsning.

En annen litt annerledes idé er å lage en egen fil index.js og gjøre

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

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

Dette har selvfølgelig ulempen at dokumentasjonen er i en egen fil.

Relaterte artikler