Build .d.ts declaration files, comments are lost and duplicates are generated.

China-xiaoFang commented 3 months ago

Describe the bug

When I try to use vite-plugin-dts to build the .d.ts declaration file of the lib. In the final result, my props and emits comments are lost. In the Demo, you can intuitively see that there are no comments in the icon.d.ts file.

I suspect the error is because I define the props and emits objects in separate files, which is why the comments are lost.

So I tried to put props and emits definitions in the same file in the ContextMenu.tsx component. In the Demo, you can intuitively see that there are comments in the contextMenu.d.ts file. Maybe I think this is a bug. It's vite-plugin-dts that doesn't handle this situation well.

And there is another problem. I must have defined the icon.tsx component and also exported it by default in the file. But in the root directory of the Icon component, I placed an index.ts file, which references the ./src/icon(.tsx) file to export and install the component name. However, in the final index.d.ts file, it seems that the declaration of the icon.d.ts file is regenerated by default. I think this effect did not meet my expectations.

Regarding the expectations of comments, I hope that no matter how I define these variables, I can include these comment information in the final .d.ts declaration file. Similar to

import { PropType } from 'vue';
import { GContextMenuData, GContextMenuStates } from './type';

/**
 * GContextMenu 组件
 */
declare const _default: import('vue').DefineComponent<{
    /**
     * 数据
     */
    data: {
        type: PropType<GContextMenuData[]>;
        default: any[];
    };
}, {
    states: GContextMenuStates;
    contextMenuRef: import('vue').Ref<HTMLElement>;
    open: (axis?: {
        x: number;
        y: number;
    }) => void;
    close: () => void;
}, unknown, {}, {}, import('vue').ComponentOptionsMixin, import('vue').ComponentOptionsMixin, {
    /**
     * 点击事件
     */
    click: (event: MouseEvent, data: GContextMenuData) => boolean;
}, string, import('vue').PublicProps, Readonly<import('vue').ExtractPropTypes<{
    /**
     * 数据
     */
    data: {
        type: PropType<GContextMenuData[]>;
        default: any[];
    };
}>> & {
    onClick?: (event: MouseEvent, data: GContextMenuData) => any;
}, {
    data: GContextMenuData[];
}, {}>;
export default _default;

The expectation for the second question is actually optional. It just increases the file size after my lib mode packaging. However, it still needs to include comment information. The best expectation should be

import { ExtractPropTypes } from 'vue';
import { gIconProps } from './src/define';
import { default as Icon } from './src/icon';

export declare const GIcon: import('../../utils/vue/typescript').TSXWithInstall<typeof Icon>;
export default GIcon;
export * from './src/define';
export * from './src/type';
export type GIconInstance = InstanceType<typeof Icon>;
export type GIconProps = ExtractPropTypes<typeof gIconProps>;

Reproduction

https://stackblitz.com/edit/vite-build-dts-error-240823

Steps to reproduce

Run npm install followed by npm run build

System Info

System:
    OS: Windows 11 10.0.22631
    CPU: (20) x64 12th Gen Intel(R) Core(TM) i7-12700
    Memory: 11.95 GB / 31.79 GB
  Binaries:
    Node: 20.15.0 - C:\Program Files\nodejs\node.EXE
    npm: 10.7.0 - C:\Program Files\nodejs\npm.CMD
    pnpm: 9.5.0 - C:\Program Files\nodejs\pnpm.CMD
  Browsers:
    Edge: Chromium (127.0.2651.74)
    Internet Explorer: 11.0.22621.3527
  npmPackages:
    @vitejs/plugin-vue: ^5.0.5 => 5.1.2 
    @vitejs/plugin-vue-jsx: ^4.0.0 => 4.0.1 
    vite: ^5.3.2 => 5.4.2 
    vite-plugin-dts: ^3.9.1 => 3.9.1

Validations

[X] Read the FAQ.
[X] Check that there isn't already an issue that reports the same bug to avoid creating a duplicate.
[X] The provided reproduction is a minimal reproducible example of the bug.

qmhc commented 3 months ago

Sadly, this is a limitation of Volar.

China-xiaoFang commented 3 months ago

Sadly, this is a limitation of Volar.

Volar? But I thought Volar shouldn't be just a plugin for an IDE? Are there any limitations on the declaration files it generates?

qmhc commented 3 months ago

You can use vue-tsc to generate the declaration files and see the limitation.

China-xiaoFang commented 3 months ago

You can use vue-tsc to generate the declaration files and see the limitation.

I understand, because I tried it with vue-tsc and it did have the same effect, but there was no comment.

Would it be more convenient if we could communicate in Chinese?

Shinigami92 commented 3 months ago

Can we link the vue-tsc issue here?

qmhc commented 3 months ago

@Shinigami92 Sure.

johnsoncodehk commented 3 months ago

This is a problem in DefineComponent type. I don't have the energy to investigate at the moment. If anyone wants to deal with it, you can refer to my past PR:

Shinigami92 commented 2 months ago

Looks like all 3 linked PRs are solved and merged. Is there something that needs to be done here? Or can the issue just get closed?

China-xiaoFang commented 2 months ago

This is a problem in DefineComponent type. I don't have the energy to investigate at the moment. If anyone wants to deal with it, you can refer to my past PR:

feat(types): simplify ExtractPropTypes to avoid props JSDocs being removed vuejs/core#5166

feat(types): avoid props JSDocs loss due to default option vuejs/core#5871

types(runtime-core): using intersection type in Readonly<...> breaks JSDoc emit vuejs/core#11799

Are these three PRs related to this issue? It seems that I have updated all packages to the latest version, but still failed to solve this problem.

China-xiaoFang commented 1 month ago

@qmhc Hello, do you have time recently? For the previous Issues, I can customize the .d.ts declaration file and replace the final duplicate file. But there is a more urgent problem, which is the problem of jsDoc document comments. Because in many cases, I define props emits including slots. So I can't put all the code in one file very elegantly, I need to reference it through different files. So it also leads to that if it is defined in different files, the final generated .d.ts declaration file does not actually have jsDoc document comments, which is extremely inefficient for our developers. I hope this jsDoc document comment problem can be solved as soon as possible. Because it really affects me. For this reason, I have re-provided a smaller Demo. https://stackblitz.com/edit/vue-tsc-jsdoc-error Thank you very much!

l246804 commented 2 weeks ago

+1

qmhc / vite-plugin-dts