[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.

Comienza revisando las brechas de paridad de JSDoc indicadas, incluidas interface, abstract class, declaration forms, namespace, enum y non-null assertions. Sigue las issues referenciadas sobre function overloading, generic defaults y as const; después determina qué brechas quedan y define los criterios de finalización para cada capacidad propuesta.