Implement a JSDoc @import tag

[DanielRosenwasser]

Background

#22158 tracks referencing types from a given module using JSDoc-style namepaths. Given that the syntax is somewhat unintuitive and predates the concept of ECMAScript modules, we would like to support a more ergonomic form if we feel it would be helpful.

Options

Bikeshedding time. 🚲 🏠

@from @import

/**
 * @from "express"
 * @import { Request, Response as CoolResponse } from
 * @import Default
 * @import * as ns
 */

Pros

• Allowing @from to precede named import clauses would be easier for completions (this is one of our oldest-duped requests Request for alternative import syntax to improve auto-complete experience #2371)
• Can have multiple import clauses
• Could hypothetically support @from before @import and vice versa.

Cons

• Doesn't totally look like ESModule syntax which is just extra cognitive overhead.

ECMAScript Import-based

/**
 * @import { x, y as z, default as Default } from "express"
 */

Pros

• Nothing to learn if you already know ECMAScript syntax.

Cons

• Less optimal for completions

Issues with the Above

The options above don't make it explicit that only types are being imported. We could play around with keyword/tag placement (e.g. @importtype, @import type, etc.)

[aozgaa]

This was previously discussed in #14377

[DanielRosenwasser]

We're going to hold off on any new JSDoc syntax, and wait for more feedback here. As per #22445, our current recommendation is to wait on #14844 and then use

/**
 * @typedef {import("express")} express
 */

[mhegazy]

closing in favor of #14844

[jkrems]

@DanielRosenwasser Did the syntax for module namespaces change? I tried scanning through the linked issues but since none of them are showing the JSDoc equivalent, it's somewhat hard to follow.

/**
 * The following works using latest typescript@next (2.9.0-dev.20180506):
 *
 * @typedef {import('http').IncomingMessage} IncomingMessage
 * @typedef {import('http').ServerResponse} ServerResponse
 *
 * But this fails:
 *
 * > Module 'http' does not refer to a type, but is used as a type here.
 *
 * @typedef {import('http')} http
 */

[mhegazy]

Use typeof:

/** @typedef {typeof import('http')} http*/