docs: expand JSDoc coverage across plugin source

[aryaemami59]

• This PR contains AI-generated code, but I have carefully reviewed it myself. Otherwise, my PR may be closed.
  • I understand that my PR is more likely to be rejected or requested for changes if it contains AI-generated code that I do not fully understand.

Description

Adds comprehensive JSDoc across the plugin's public API and internal helpers, and folds in a small set of trivial cleanups noticed along the way. No runtime behavior changes.

What changed

Documentation (the bulk)

JSDoc blocks added to:

• Public API: Options, GeneralOptions, TscOptions, TsgoOptions, OptionsResolved, resolveOptions, dts (src/options.ts, src/index.ts).
• Plugin internals: src/fake-js.ts, src/generate.ts, src/dts-input.ts, src/resolver.ts, src/tsgo.ts, src/filename.ts, src/debug.ts.
• TypeScript-compiler integration: entire src/tsc/ directory (context.ts, emit-build.ts, emit-compiler.ts, index.ts, resolver.ts, system.ts, types.ts, utils.ts, volar.ts, worker.ts).

Comments document parameter contracts, return shapes, defaults, and invariants, using {@linkcode} cross-references and @example blocks (notably for entry, tsgo, cjsDefault, and invalidateContextFile).

Correctness / cleanup fixes

• Typo: RuntimeBindingVariableDeclration → RuntimeBindingVariableDeclaration (src/fake-js.ts; snapshots updated under __snapshots__/tsnapi/).
• Param rename: comment → comments in collectReferenceDirectives (src/fake-js.ts).
• Removed redundant cast: node.specifiers[0] as t.ExportSpecifier (src/fake-js.ts); the surrounding type guard already narrows.
• Removed no-op Omit: Omit<TscOptions, 'programs'> → TscOptions (src/generate.ts); programs was never a key.
• DRYed internal type: TscOptions in src/tsc/types.ts now extends Required<Pick<Options, …>> & Pick<Options, …> instead of redeclaring tsconfig, tsconfigRaw, cwd, build, incremental, sourcemap, vue, tsMacro.
• Corrected tsconfig default: Options.tsconfig was documented as @default 'tsconfig.json', but resolveOptions treats true and omitted identically (upward search via get-tsconfig, not a literal path.resolve(cwd, 'tsconfig.json')). Now documented as @default true with the three input branches (true / string / false) each explained, matching tsdown and rolldown.

Stylistic refactor (intentional, doc-driven)

Seven functions switched from inline-destructured params to a single named param destructured in the body, so JSDoc has a clean @param target:

• createDtsInputPlugin (src/dts-input.ts)
• createFakeJsPlugin (src/fake-js.ts)
• createGeneratePlugin (src/generate.ts)
• createDtsResolvePlugin (src/resolver.ts)
• resolveOptions (src/options.ts) - uses let because several destructured bindings are reassigned during normalization.
• createTsProgram, createTsProgramFromParsedConfig (src/tsc/emit-compiler.ts).

Why

The plugin's public surface had thin documentation. Hovering an option in an editor, or generating an API reference, surfaced little beyond the type. This PR fixes that without touching runtime behavior, and sweeps up a handful of pre-existing nits encountered along the way.

Verification

• pnpm run build - typecheck + bundle pass.
• pnpm test - snapshot suite passes; updated snapshots reflect the identifier typo fix only.
• Spot-checked hover docs in the editor for dts, Options, GeneralOptions, TscOptions, TsgoOptions.

Out of scope (future work)

• Two interfaces named TscOptions exist (public in src/options.ts and internal in src/tsc/types.ts). They are intentionally distinct but share a name, which is confusing - worth renaming the internal one in a follow-up.

Linked Issues

Additional context

[pkg-pr-new]

Open in StackBlitz

npm i https://pkg.pr.new/rolldown-plugin-dts@236

commit: 341a211

[sxzz]

Looks like it's generated by AI.

[aryaemami59]

Looks like it's generated by AI.

some of it yeah, the majority of the JSDocs especially the added links and fixed defaults and the added examples were my doing, I am slowly working towards finishing rolldown/tsdown#679, and this PR contributes to that as well.

[sxzz]

Thanks for the PR.

I'm leaning towards not accepting this as-is. Adding comments to almost every piece of code does not provide much value in my opinion, and mostly adds noise to the codebase.

That said, I do agree that some public APIs could use more detailed documentation. I’d be happy to keep or review changes that focus specifically on improving docs for public-facing APIs.

[aryaemami59]

Thanks for the PR.

I'm leaning towards not accepting this as-is. Adding comments to almost every piece of code does not provide much value in my opinion, and mostly adds noise to the codebase.

That said, I do agree that some public APIs could use more detailed documentation. I’d be happy to keep or review changes that focus specifically on improving docs for public-facing APIs.

no problem, I'll adjust the PR accordingly.