Support import syntax (and possibly deprecate module syntax)

[brettz9]

Expected behavior

Allow this Typescript syntax:

/**
 * @param p { import("./a").Pet }
*/

I'd personally also hope to see module: deprecated (at least eventually):

/**
 * @param p { module:a.Pet }
*/

...because:

1. According to this comment, it is the only deliberate deviation of TypeScript from jsdoc and the only expected one.
2. It is useful in its own right for documentation to make clear from where a module is being obtained, whether the path is a relative one, or as is apparently also allowed, one based on the well-used Node resolution algorithm.

Current behavior

Currently, the module syntax is not compatible with those wishing to move to Typescript (or considering doing so), or those using Typescript who wish to confine themselves to the subset supported by jsdoc3 so as to be able to take advantage of jsdoc3/jsdoc.

[GrosSacASac]

jsdoc does not follow imports by default #1577

[brettz9]

I am referring to Typescript's style of imports; see, e.g.: https://github.com/openlayers/jsdoc-plugin-typescript#typescript

[brettz9]

The quotation marks in @external targeted paths appears to be another one of the few "won't fix"'s of TypeScript relative to JSDoc (see jsdoctypeparser/jsdoctypeparser#58 (comment) ), so I should make explicit here the desire that the desired import statements also handle the case of @external paths, i.e., non-resolved paths.

Hopefully if accepting this issue as I hope would be the case for mutual compatibility, JSDoc, might allow, at least through plugin, the ability to check such non-browser-resolvable paths (especially according to the Node Resolution Algorithm), so that they could be confirmed in some way.

So that, e.g.:

/** @type {import("jQuery.fn").starfairy} */

...could be confirmed as a valid path, and even possibly link to source code.

Actually, since jQuery doesn't export "fn", I guess it should be:

/** @type {import("jQuery").fn.starfairy} */

@sandersn

[hegemonic]

I think this qualifies as a duplicate of #1645.

[nbilyk]

A jsdoc plugin to workaround to this problem (or at least the case of relative imports):
https://github.com/polyforest/jsdoc-tsimport-plugin/