[Design Policy] Consider JSDoc feature parity with Typescript

Search Terms

jsdoc parity, jsdoc equivalence, jsdoc

Suggestion

The JSDoc mode of TypeScript is very useful in cases where a build step (esp for node libraries for example) isn't desired or when other constraints prevent not writing in JS. However it can be annoying when trying to implement something that can't be expressed in JSDoc mode due to requiring Typescript syntax.

As such I would like to propose that TypeScript ensures that anything that can be written inside a .ts file can be expressed (in at least some way) within a pure javascript + jsdoc file.

In order to get an idea of the current scope needed for feature parity this is a list of issues and features that break parity between the two modes (if any are missing just say and I'll add to the list):

• [Bug?] No way to express the object type
  • Currently in JSDoc /** @type {object} */ is equivalent to /** @type {any} */, there doesn't seem to be any way to represent const x: object purely in JS + JSDoc, this seems like a bug. Fixed
• interface
• abstract class
• protected/private members Fixed
• function overloading v5.0
  • open issue
• defaults for generics
  • open issue
• declare syntax in it's various forms and declaration merging
  • declare global { ... }
  • declare module "moduleName"
  • declare class Foo
  • declare interface
  • declare namespace
• namespace
• enum
  • /** @enum */ is not quite equivalent
• as const v4.5
  • open issue
• non-null assertion expr!

Checklist

My suggestion meets these guidelines:

• [✓] 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, etc.)
• [✓] This feature would agree with the rest of TypeScript's Design Goals.

Start by reviewing the listed JSDoc parity gaps, including interface, abstract class, declaration forms, namespace, enum, and non-null assertions. Follow the referenced issues for function overloading, generic defaults, and as const, then determine which gaps remain and define completion criteria for each proposed capability.