Document the JSDoc @import tag (#3170)

Co-authored-by: Daniel Rosenwasser <[email protected]>
Co-authored-by: Jake Bailey <[email protected]>

Author: 3 people

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`