Skip to content

Plugin to make TypeScript's JSDoc type annotations work with JSDoc

License

Notifications You must be signed in to change notification settings

KlausBenndorf/jsdoc-plugin-typescript

 
 

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 

History

24 Commits
 
 
 
 
 
 
 
 

Repository files navigation

jsdoc-plugin-typescript

Plugin to make TypeScript's JSDoc type annotations work with JSDoc. Requires JSDoc v3.6.0 or higher.

Installation and use

JSDoc accepts plugins by simply installing their npm package:

npm install --save-dev jsdoc-plugin-typescript

To configure JSDoc to use the plugin, add the following to the JSDoc configuration file, e.g. conf.json:

"plugins": [
  "jsdoc-plugin-typescript"
],
"typescript": {
  "moduleRoot": "src"
}

See http://usejsdoc.org/about-configuring-jsdoc.html for more details on how to configure JSDoc.

In the above snippet, "src" is the directory that contains the source files. Inside that directory, each .js file needs a @module annotation with a path relative to that "moduleRoot", e.g.

/** @module ol/proj **/

What this plugin does

When using the class keyword for defining classes (required by TypeScript), JSDoc requires @classdesc and @extends annotations. With this plugin, no @classdesc and @extends annotations are needed.

Types defined in a project are converted to JSDoc module paths, so they can be documented and linked properly.

In addition to types that are used in the same file that they are defined in, imported types are also supported.

TypeScript and JSDoc use a different syntax for imported types:

TypeScript

Named export:

/**
 * @type {import("./path/to/module").exportName}
 */

Default export:

/**
 * @type {import("./path/to/module").default}
 */

typeof type:

/**
 * @type {typeof import("./path/to/module").exportName}
 */

JSDoc

Named export:

/**
 * @type {module:path/to/module.exportName}
 */

Default export assigned to a variable in the exporting module:

/**
 * @type {module:path/to/module~variableOfDefaultExport}
 */

This syntax is also used when referring to types of @typedefs and @enums.

Anonymous default export:

/**
 * @type {module:path/to/module}
 */

typeof type:

/**
 * @type {Class<module:path/to/module.exportName>}
 */

About

Plugin to make TypeScript's JSDoc type annotations work with JSDoc

Resources

License

Stars

Watchers

Forks

Packages

No packages published

Languages

  • JavaScript 100.0%