Skip to content

Implement a JSDoc @import tag #22160

Closed
@DanielRosenwasser

Description

@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

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.)

Activity

aozgaa

aozgaa commented on Feb 26, 2018

@aozgaa
Contributor

This was previously discussed in #14377

DanielRosenwasser

DanielRosenwasser commented on Mar 9, 2018

@DanielRosenwasser
MemberAuthor

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
 */
removed
Awaiting More FeedbackThis means we'd like to hear from more people who would be helped by this feature
Domain: JSDocRelates to JSDoc parsing and type generation
on Mar 9, 2018
mhegazy

mhegazy commented on Mar 9, 2018

@mhegazy
Contributor

closing in favor of #14844

jkrems

jkrems commented on May 7, 2018

@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

mhegazy commented on May 7, 2018

@mhegazy
Contributor

Use typeof:

/** @typedef {typeof import('http')} http*/
locked and limited conversation to collaborators on Jul 31, 2018

63 remaining items

Loading
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    Domain: JSDocRelates to JSDoc parsing and type generationDomain: JavaScriptThe issue relates to JavaScript specificallySuggestionAn idea for TypeScript

    Type

    No type

    Projects

    No projects

    Relationships

    None yet

      Development

      Participants

      @bmeck@rjgotten@jkrems@DanielRosenwasser@nojvek

      Issue actions

        Implement a JSDoc @import tag · Issue #22160 · microsoft/TypeScript