Deprecate Vue Components, props, slots, events ...

[Shinigami92]

A bit related to #2285 but bigger scope

At #VueAmsterdam2023 the idea came up to make it possible to deprecate all the things like a whole component, named slots, emitters and so on via Volar so it will be displayed as strikethrough in VSCode (and maybe other IDEs)

So for example things like that:

<script setup lang="ts">
import MyDeprecatedComponent from '@/components/MyDeprecatedComponent.vue'
</script>

<template lang="pug">
MyDeprecatedComponent
//- ^ ~~~~~~~~~~~~~ ^

MyDeprecatedComponent
  template(#header="{ deprecatedItem, nonDeprecated }")
  //-       ^~~~~^    ^~~~~~~~~~~~~^
</template>

It might be that we need to add some new language features to vue/vue-macros to support this

e.g.

defineOptions({
  name: 'MyDeprecatedComponent',
  deprecated: 'Reason...',
})

[xiaoxiangmoe]

Here is a simple example we can use now.

<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">
defineProps<{
  /**
   * Set button type
   */
  buttonType?: 'primary' | 'dashed' | 'link' | 'text' | 'default';
}>();
</script>
<template>
  <button></button>
</template>

We can hover to default to see jsdoc for the component self

And hover to the component import statement to see jsdoc imported

---

But displayed as strikethrough in VSCode only works in <script> block, not in <template> block

Also there is no jsdoc in component used

[serenayl]

Thank you for adding support for this, what syntax can we use to take advantage of the feature to directly document with script setup?

This issue was closed and it looks like the appropriate support was added in 2.0.19. I have updated my VSCode extension to the latest 2.0.19 and am attempting to use JSDoc at a component level with script setup. However, I'm not able to see any annotations in the template which calls it.

Neither of these seem to yield any documentation:

<script setup lang="ts">
/** JSDoc description without defineOptions */

/** JSDoc description for defineOptions */
defineOptions({
    name: 'MyComponent',
})

...
</script>

[vinodkola1337]

Thank you for adding support for this, what syntax can we use to take advantage of the feature to directly document with script setup?

This issue was closed and it looks like the appropriate support was added in 2.0.19. I have updated my VSCode extension to the latest 2.0.19 and am attempting to use JSDoc at a component level with script setup. However, I'm not able to see any annotations in the template which calls it.

Neither of these seem to yield any documentation:

<script setup lang="ts">
/** JSDoc description without defineOptions */

/** JSDoc description for defineOptions */
defineOptions({
    name: 'MyComponent',
})

...
</script>

It doesn't work with <script setup>, for more details refer https://stackoverflow.com/questions/72003493/how-to-use-jsdoc-to-document-a-vue-component-with-script-setup

[serenayl]

It doesn't work with <script setup>, for more details refer https://stackoverflow.com/questions/72003493/how-to-use-jsdoc-to-document-a-vue-component-with-script-setup

I believe this is historically the case, but it appears as though support for this was added or at least unblocked in #3651 two weeks ago, and based on the changelog it looks like that change been released since being merged.

[vinodkola1337]

@serenayl - My bad, I completely missed that this is supported now.

I did testing by updating to the latest version (2.019) and it didn't worked for me either.

Thank you for pointing it out, eagerly waiting for this functionality.