Add JSDoc for all configuration options as webpack

[chenjiahan]

What problem does this feature solve?

Can we add JSDoc for all configuration options as webpack?

• webpack:

• Rspack:

What does the proposed API of configuration look like?

Same as webpack:

[hyf0]

The type of rspack options is inferred by zod. It's not possible in the current time. See colinhacks/zod#200 (comment) for details.

[chenjiahan]

It seems that JSDoc can work in some cases:

colinhacks/zod#200 (comment)

[dinckelman]

This appears to be very much situational, because as shown below, VSCode cannot detect the comment, and Webstorm is... well, trying to do something else entirely

[hardfist]

it indeed hurt DX for users，we will try to find better ways to do this

[stale]

This issue has been automatically marked as stale because it has not had recent activity. If this issue is still affecting you, please leave any comment (for example, "bump"). We are sorry that we haven't been able to prioritize it yet. If you have any new additional information, please include it with your comment!

[chenjiahan]

bump

[stale]

This issue has been automatically marked as stale because it has not had recent activity. If this issue is still affecting you, please leave any comment (for example, "bump"). We are sorry that we haven't been able to prioritize it yet. If you have any new additional information, please include it with your comment!

[xc2]

bump

[stale]

This issue has been automatically marked as stale because it has not had recent activity. If this issue is still affecting you, please leave any comment (for example, "bump"). We are sorry that we haven't been able to prioritize it yet. If you have any new additional information, please include it with your comment!

[chenjiahan]

bump

[stale]

This issue has been automatically marked as stale because it has not had recent activity. If this issue is still affecting you, please leave any comment (for example, "bump"). We are sorry that we haven't been able to prioritize it yet. If you have any new additional information, please include it with your comment!

[chenjiahan]

bump

[stale]

This issue has been automatically marked as stale because it has not had recent activity. If this issue is still affecting you, please leave any comment (for example, "bump"). We are sorry that we haven't been able to prioritize it yet. If you have any new additional information, please include it with your comment!

[hardfist]

the zod type definition is too complex to maintain and read in d.ts, we may consider go back to handwritten json schema with comment support

[chenjiahan]

@hardfist handwritten json schema or handwritten config types?

[ecraig12345]

In addition to the missing documentation, it's extremely hard to understand the generated zod types when looking at the .d.ts or intellisense in an editor. And it seems like TS can't always infer the types of functions in complex union types--I filed a bug #7979 for externals functions specifically.

[GiveMe-A-Name]

I have some ideas about this.

1. One is using json schema, like webpack. It means we need maintain a json schema.
2. Another one is that maintain another types for UX. Like the code bellow:

interface Address {
    id?: string
    addressText: string
    line1: string
    line2?: string
    city: string
    state: string
    postalCode: string
    country: string
}

const addressSchema = z.object( {
    id: z.string().optional(),
    addressText: z.string(),
    line1: z.string(),
    line2: z.string().optional(),
    city: z.string(),
    state: z.string(),
    postalCode: z.string(),
    country: z.string(),
} ) satisfies z.ZodType<Address>

see colinhacks/zod#1870 more detail.

Actually, if we can transform ts to zod or zod to ts, it's a better way. But Rspack Configuration types is so complex, ts-to-zod can't transform it correctly.
see colinhacks/zod#779 more transform way.

So I prefer second way. But the drawback is we need maintain a another types.

[chenjiahan]

The second one LGTM 👍 If we take this approach, we can incrementally migrate types and add JSDoc comments.

[GiveMe-A-Name]

Tasks

• refactor: add JSDoc to improve BannerPlugin options types #8003
• refactor: add JSDoc & types to improve HtmlRspackPlugin, IgnorePlugin options types #8004
• refactor: add JSDoc to improve Rspack configuration.entry|context|mode types #8016
• refactor: add JSDoc to improve Rspack configuration.output types.
• refactor: add JSDoc to improve Rspack configuration.module types.
• refactor: add JSDoc & types to improve configuration.resolve types. #8029
• refactor: add JSDoc to improve Rspack configuration.optimization types.
• refactor: add JSDoc to improve Rspack configuration.devServer types.
• refactor: add JSDoc to improve Rspack configuration.watch types.
• refactor: add JSDoc to improve configuration.externals types #8013
• refactor: add JSDoc to improve Rspack configuration.performance types.
• refactor: add JSDoc to improve Rspack configuration.stats types.
• refactor: add JSDoc to improve Rspack configuration.experiments types.
• refactor: add JSDoc to improve Rspack configuration.stats types.