vue-styleguidist: How to document a Component inside "script setup" blocks?

Hi there!

How to document it? Slots, props and events are working fine. But how to set the basic Component description?

<script setup lang="ts">
/**
 * This should show up somewhere.
 */
...
</script>

About this issue

  • Original URL
  • State: closed
  • Created 4 years ago
  • Comments: 17 (6 by maintainers)

Commits related to this issue

Most upvoted comments

I didn’t go too much further and just went with this in the configs. To also not need to do much processing, I went with this style of doc for the component:

    /*@component
    This is the doc for the component.
    It does not have that * prefix for each line but you can probably easily fix parser.
    */
    apiOptions: {
        addScriptHandlers: [
            function (
                documentation,
                componentDefinition,
                astPath,
                opt
            ) {
                const componentDoc = astPath.tokens.filter(token => token.type === 'CommentBlock' && token.value.includes('@component')).find(() => true);
                if (componentDoc) {
                    const lines = componentDoc.value.split('\n');

                    documentation.set('description', lines.filter(line => !line.includes('@component')).map(line => line.substring(componentDoc.loc.indent)).join('\n'));
                }
            }
        ]
    },

@elevatebart @David-Mueller

/**
  * Overridden component description
  * @version 12.5.7
  * @author [Rafael]
  * @example path/to/example.md
  * @displayName Best Button Ever
  */
defineOptions({
  name: 'VSGButton'
})

This is not help for see jsdoc for the component self. We can use it instead

<script lang="ts">
/**
 * # My Button Component
 * To trigger an operation.
 * 
 * @deprecated Please use `MyButtonV2` instead.
 * 
 * @example
 * ```vue
 * <MyButton>Click Me</MyButton>
 * ```
 */
export default {};
</script>
<script setup lang="ts">
interface MyButtonProps {
  /**
   * Set button type
   */
  buttonType?: 'primary' | 'dashed' | 'link' | 'text' | 'default';
}
defineProps<MyButtonProps>();
</script>
<template>
  <button></button>
</template>
image

Not included for now. For me it is sufficient the title derived from the filename. Anyway, I think to include a split of the string (text) on @component and then on @displayName to extract the contents. Hope it helps.

FYI for us, the <docs>...</docs> block worked fine with a vite plugin:

export const vueDocsPlugin = () => ({
  name: 'vue-docs',
  transform(code, id) {
    if (!/vue&type=docs/.test(id))
      return;
    return `export default ''`;
  }
});