diff --git a/packages/documentation/copy/en/javascript/JSDoc Reference.md b/packages/documentation/copy/en/javascript/JSDoc Reference.md index 7cd5d7b23e06..e2e1cb28af80 100644 --- a/packages/documentation/copy/en/javascript/JSDoc Reference.md +++ b/packages/documentation/copy/en/javascript/JSDoc Reference.md @@ -16,6 +16,7 @@ Note: #### Types - [`@type`](#type) +- [`@import`](#import) - [`@param`](#param-and-returns) (or [`@arg`](#param-and-returns) or [`@argument`](#param-and-returns)) - [`@returns`](#param-and-returns) (or [`@return`](#param-and-returns)) - [`@typedef`](#typedef-callback-and-param) @@ -198,7 +199,31 @@ function walk(p) { } ``` -import types can be used in type alias declarations: +import types can be used to get the type of a value from a module if you don't know the type, or if it has a large type that is annoying to type: + +```js twoslash +// @filename: accounts.d.ts +export const userAccount = { + name: "Name", + address: "An address", + postalCode: "", + country: "", + planet: "", + system: "", + galaxy: "", + universe: "", +}; +// @filename: main.js +// ---cut--- +/** + * @type {typeof import("./accounts").userAccount} + */ +var x = require("./accounts").userAccount; +``` + +### `@import` + +The `@import` tag can let us reference exports from other files. ```js twoslash // @filename: types.d.ts @@ -208,7 +233,7 @@ export type Pet = { // @filename: main.js // ---cut--- /** - * @typedef {import("./types").Pet} Pet + * @import {Pet} from "./types" */ /** @@ -218,26 +243,20 @@ var myPet; myPet.name; ``` -import types can be used to get the type of a value from a module if you don't know the type, or if it has a large type that is annoying to type: +These tags don't actually import files at runtime, and the symbols they bring into scope can only be used within JSDoc comments for type-checking. ```js twoslash -// @filename: accounts.d.ts -export const userAccount = { - name: "Name", - address: "An address", - postalCode: "", - country: "", - planet: "", - system: "", - galaxy: "", - universe: "", -}; +// @filename: dog.js +export class Dog { + woof() { + console.log("Woof!"); + } +} + // @filename: main.js -// ---cut--- -/** - * @type {typeof import("./accounts").userAccount} - */ -var x = require("./accounts").userAccount; +/** @import { Dog } from "./dog.js" */ + +const d = new Dog(); // error! ``` ### `@param` and `@returns`