Make JSDoc Parsing Configurable using the transpileModule method

[mpodwysocki]

🔍 Search Terms

transpileModule jsDocParsingMode

✅ Viability Checklist

• This wouldn't be a breaking change in existing TypeScript/JavaScript code
• This wouldn't change the runtime behavior of existing JavaScript code
• This could be implemented without emitting different JS based on the types of the expressions
• This isn't a runtime feature (e.g. library functionality, non-ECMAScript syntax with JavaScript output, new syntax sugar for JS, etc.)
• This isn't a request to add a new utility type: https://github.com/microsoft/TypeScript/wiki/No-New-Utility-Types
• This feature would agree with the rest of our Design Goals: https://github.com/Microsoft/TypeScript/wiki/TypeScript-Design-Goals

⭐ Suggestion

In #55739 there was an addition to ts. createSourceFile which allowed to opt into parsing JSDocs, which until then had been opt-in by default. This API, however, was not added to the ts.transpileModule where the Azure SDK for JavaScript currently uses to create samples.

📃 Motivating Example

We currently use the TypeScript compiler to parse our TypeScript files to convert them to JavaScript such as the following:

  const output = ts.transpileModule(processedSrcText, {
    compilerOptions: {
      ...compilerOptions,
      ...extraCompilerOptions,
      removeComments: false,
    },
    ...transpileOptions,
  });

Upgrading to 5.3 from 5.2 caused us to lose our JSDoc comments as opting into JSDoc parsing is hard coded in this case to not include them. The ideal solution would be to do the following to add the jsDocParsingMode to the TranspileOptions such as the tollowing:

transpileOptions.jsDocParsingMode = ts.JSDocParsingMode.ParseAll;

💻 Use Cases

1. What do you want to use this for? This is used as part of our workflow convert our existing samples from TypeScript to JavaScript and retain all of our JSDocs from TypeScript to apply to JavaScript.
2. What shortcomings exist with current approaches? With 5.3, we no longer have the ability to read these comments through the ts.transpileModule method as it is hard coded to ts.JSDocParsingMode.ParseNone
3. What workarounds are you using in the meantime? None as we cannot upgrade to TypeScript 5.3 unless this option is introduced.

[andrewbranch]

Note to maintainers: the thing that makes this relevant to ts.tranpileModule is the fact that custom transformers can be passed in, which see the parse tree. It was probably omitted from this API because the basic usage is just text in, text out.

[jakebailey]

Reading the above implies that the JSDoc was actually removed from the output JS code; my intention was that it was safe to pass ParseNone here because that would mean that we skipped actually parsing the nodes themselves and they'd just be regular comments that were output like non-jsdoc comments. Is that not the case? Or are you actually using transformers somehow in the above? (You didn't say one way or the other.)

[andrewbranch]

The issue isn't about emit at all; Azure is doing some fancy stuff with reading JSDoc nodes in transformers. (This issue was filed at my request after offline discussion)