From 4e8958eb3845048ba91a739f8fc8cfaff9f26c82 Mon Sep 17 00:00:00 2001 From: Remco Haszing Date: Fri, 28 Jun 2024 12:23:11 +0200 Subject: [PATCH 1/4] Document the JSDoc @import tag This replaces the documentation for using `@typedef` and `import()` to alias a type. --- .../copy/en/javascript/JSDoc Reference.md | 43 ++++++++++--------- 1 file changed, 23 insertions(+), 20 deletions(-) diff --git a/packages/documentation/copy/en/javascript/JSDoc Reference.md b/packages/documentation/copy/en/javascript/JSDoc Reference.md index 76bdfc182523..91e04c14da2d 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,26 +199,6 @@ function walk(p) { } ``` -import types can be used in type alias declarations: - -```js twoslash -// @filename: types.d.ts -export type Pet = { - name: string, -}; -// @filename: main.js -// ---cut--- -/** - * @typedef {import("./types").Pet} Pet - */ - -/** - * @type {Pet} - */ -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: ```js twoslash @@ -240,6 +221,28 @@ export const userAccount = { var x = require("./accounts").userAccount; ``` +### `@import` + +`@import` can be used for type-only imports: + +```js twoslash +// @filename: types.d.ts +export type Pet = { + name: string, +}; +// @filename: main.js +// ---cut--- +/** + * @import {Pet} from "./types" + */ + +/** + * @type {Pet} + */ +var myPet; +myPet.name; +``` + ### `@param` and `@returns` `@param` uses the same type syntax as `@type`, but adds a parameter name. From 5dbbc0b63c88e1313eaa40b25a212a6c26d98808 Mon Sep 17 00:00:00 2001 From: Remco Haszing Date: Fri, 10 Jan 2025 11:16:29 +0100 Subject: [PATCH 2/4] Apply suggestions from code review Co-authored-by: Daniel Rosenwasser --- .../copy/en/javascript/JSDoc Reference.md | 16 +++++++++++++++- 1 file changed, 15 insertions(+), 1 deletion(-) diff --git a/packages/documentation/copy/en/javascript/JSDoc Reference.md b/packages/documentation/copy/en/javascript/JSDoc Reference.md index b9bfeaffe681..5ba603e171ff 100644 --- a/packages/documentation/copy/en/javascript/JSDoc Reference.md +++ b/packages/documentation/copy/en/javascript/JSDoc Reference.md @@ -223,7 +223,7 @@ var x = require("./accounts").userAccount; ### `@import` -`@import` can be used for type-only imports: +The `@import` tag can let us reference exports from other files. ```js twoslash // @filename: types.d.ts @@ -243,6 +243,20 @@ var myPet; myPet.name; ``` +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: dog.js +export class Dog { + woof() { + console.log("Woof!"); + } +} + +// @filename: main.js +/** @import { Dog } from "./dog.js"; + +const d = new Dog(); // error! ### `@param` and `@returns` `@param` uses the same type syntax as `@type`, but adds a parameter name. From a39918fd15f57ae1d80a0e28b333a17f9fc0a1e9 Mon Sep 17 00:00:00 2001 From: Jake Bailey <5341706+jakebailey@users.noreply.github.com> Date: Mon, 13 Jan 2025 13:00:26 -0800 Subject: [PATCH 3/4] Update packages/documentation/copy/en/javascript/JSDoc Reference.md --- packages/documentation/copy/en/javascript/JSDoc Reference.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/packages/documentation/copy/en/javascript/JSDoc Reference.md b/packages/documentation/copy/en/javascript/JSDoc Reference.md index 5ba603e171ff..258293f910dc 100644 --- a/packages/documentation/copy/en/javascript/JSDoc Reference.md +++ b/packages/documentation/copy/en/javascript/JSDoc Reference.md @@ -257,6 +257,8 @@ export class Dog { /** @import { Dog } from "./dog.js"; const d = new Dog(); // error! +``` + ### `@param` and `@returns` `@param` uses the same type syntax as `@type`, but adds a parameter name. From 313bbf6b41f4dcb2e1033a939ec120d1998a6f7b Mon Sep 17 00:00:00 2001 From: Jake Bailey <5341706+jakebailey@users.noreply.github.com> Date: Mon, 13 Jan 2025 13:48:57 -0800 Subject: [PATCH 4/4] Update packages/documentation/copy/en/javascript/JSDoc Reference.md --- packages/documentation/copy/en/javascript/JSDoc Reference.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/packages/documentation/copy/en/javascript/JSDoc Reference.md b/packages/documentation/copy/en/javascript/JSDoc Reference.md index 258293f910dc..e2e1cb28af80 100644 --- a/packages/documentation/copy/en/javascript/JSDoc Reference.md +++ b/packages/documentation/copy/en/javascript/JSDoc Reference.md @@ -254,7 +254,7 @@ export class Dog { } // @filename: main.js -/** @import { Dog } from "./dog.js"; +/** @import { Dog } from "./dog.js" */ const d = new Dog(); // error! ```