jsdoc/valid-types throwing warning when using import syntax

[mezbaul-h]

Expected behavior

Plugin should allow us to import types from separate file without warning/error.

Actual behavior

8:0  warning  Syntax error in type: import('../typedefs').ExtractorOption  jsdoc/valid-types

ESLint Config

module.exports = {
  'extends': ['eslint:recommended', 'plugin:jsdoc/recommended'],
  'env': {
    'es6': true,
    'node': true,
  },
  'parserOptions': {
    'ecmaVersion': 2018,
  },
};

ESLint sample

class BaseExtractor {
  /**
   *
   * @param {import('../typedefs').ExtractorOption} props Extractor options.
   */
  constructor(props) {
    this._options = props;
  }
}

Environment

• Node version: 12.16.3
• ESLint version: 7.4.0
• eslint-plugin-jsdoc version: 28.6.1

[brettz9]

import is not currently supported standard jsdoc syntax.

You can either:

1. Switch to jsdoc-only syntax, using @module and module: paths (in place of using import() within jsdoc types).
2. Use @typescript-eslint/parser as your parser in .eslintrc.* (which will trigger "typescript" mode by default; see the next item).
3. Explicitly add settings.jsdoc.mode to your .eslintrc.* file, setting the mode to "typescript" or, if you really must support jsdoc and typescript, "permissive" (the latter is not recommended, however).

Bear in mind that if switching to TypeScript, TypeScript (and thus our "typescript" mode) does not support all of jsdoc. See https://www.typescriptlang.org/docs/handbook/jsdoc-supported-types.html for the supported tags and types.

The mode/dialect you choose depends on how you intend to use jsdoc.

Closing as that should resolve, though feel free to comment further as needed.

[janokacer]

Hello, I have the same problem. This used to work with eslint-plugin-jsdoc version 27.1.2.

[brettz9]

@janokacer : Please read the comments for short threads like this one before posting. Thanks.

[thernstig]

@brettz9 I do not find any of the 3 options great for us, do you have some other recommendation? Let me give an example:

For 1) we have this code below. In e.g. VS Code this does not give IntelliSense when hovering Express in the @typedef part. I.e. I cannot ctrl+click to go to the declaration. It does however give IntelliSense in the function docs for Express.Request and .req.

/** @typedef {module:express} Express */

/**
 * @param {Express.Request} options.log.req - Express request object
 */
function foo(options) {

Both 2) and 3) seem to indicate we cannot use all JSDoc features, which we want.

Is there any way for eslint-plugin-jsdoc to just ignore /** @typedef {import('express')} Express */? It currently gives:

Syntax error in type: import('express')eslintjsdoc/valid-types

[brettz9]

Did you try item no. 3? Otherwise, I think this is really more of a bug (or feature request) for VS Code. But with Microsoft being behind VS Code and TypeScript, and with TypeScript indicating they will not support module: (at least for TypeScript), I'm not sure they will be working hard to get their IDE to support jsdoc. Unless you find an Atom developer to add the support, you may have to go with TypeScript mode. Though I am not a regular user myself (and don't intend to be), you can use TypeScript tooling with plain JavaScript as well.

[thernstig]

I understood item no.3 that neither typescript (due not supporting all JSDoc features) nor permissive (not recommended) was the way to go. So you recommend to use item no.3 and use typescript anyway?

[brettz9]

I think tools are likely to be built for either jsdoc or TypeScript. We normally recommend one or the other of the modes. While we do have the "permissive" mode which tries to allow you to do what we think is the more permissive, in case you have tools that support both well or if you really want to use the semantics of both together. But most projects are probably going to want to ensure that the features they are using are going to be supported in the tools they are using (e.g., jsdoc or TypeScript tools), so that is the normally recommended approach. We don't want to recommend a mode that may not be usable for actual documentation tools! But we offer such a mode since it is easy enough to allow, and perhaps some tools can work with both types.

If you know the tools you want to use, and are enforcing one mode consistently, you will have less reason to be disappointed when it comes time to build your documentation. (It's not always clear what "support" means anyways; a tool may not complain about something, but it might not display it very intelligently, for example.)

Determining our "permissive" mode wasn't always clear in some cases though; although I can't think of the specific example now, it was not possible in every situation to say something like "just support both module: and import()!"; sometimes we had to make a compromise and lean one way or the other. For those who want to use it, we hope the mode works for them, but no, we don't normally recommend that.

To get the advantages of both, you will either need to build tools yourself that utilize them, or you can indicate your support or subscribe to the issues where TypeScript (or Closure or jsdoc) is seeking to support more missing features.

For newcomers, I would probably suggest looking into TypeScript-flavor jsdoc ("typescript" mode if you don't need to add a TypeScript parser) because it has a very active community, it has actively-maintained tooling, and because I think such trends tend to win out in the long term (if they haven't already).

That doesn't even mean you have to use TypeScript-only features (in fact, I think jsdoc blocks can give you a lot of the benefits without needing to express types everywhere)--I'm here merely recommending the TypeScript-style jsdoc mode. I'd personally recommend confining yourself to it unless you have an old project or some other reason to stick with jsdoc mode.

[thernstig]

Appreciate the answer! I re-read the comment twice, but am not 100% sure what I should do in my case. I.e a VS Code user using JS Doc and ESLint with eslitn-plugin-jsdoc, but no TypeScript. It sounds like I should use permissive at first, but later in the text you seem to lean towards that I should use typescript flavor of this plugin anyway?

I think tools are likely to be built for either jsdoc or TypeScript.

In e.g. VS Code, they do heavily support both TypeScript (for IntelliSense) as well as JSDoc. If you type /** in VS Code for a function that has no documentation, it will automatically add a scaffolding to fill in JSDoc. So if we would classify VS Code as a "tool" then it has the ambition to support both.

[brettz9]

Appreciate the answer! I re-read the comment twice, but am not 100% sure what I should do in my case. I.e a VS Code user using JS Doc and ESLint with eslitn-plugin-jsdoc, but no TypeScript. It sounds like I should use permissive at first, but later in the text you seem to lean towards that I should use typescript flavor of this plugin anyway?

If your documentation tool is JSDoc, you probably want to use jsdoc mode. You might try typedoc, however, as that should be built for TypeScript support. But yes, otherwise, I'd probably recommend "typescript" mode (but I am not the one to ask in terms of what works best for various tooling). I can't make the decision for you, and this really isn't a place for support questions. You can ask on StackOverflow or such. You could also ask on our Discord chat and see if others have ideas or suggestions there.

But it's your call, I can't make the decision for you, even while I have made a limited personal opinion that "typescript" mode might be the most future-proof for new projects, at least if one wishes TypeScript-aware tools to fully "support" the tag beyond just not complaining when it is used.

I think tools are likely to be built for either jsdoc or TypeScript.

In e.g. VS Code, they do heavily support both TypeScript (for IntelliSense) as well as JSDoc. If you type /** in VS Code for a function that has no documentation, it will automatically add a scaffolding to fill in JSDoc. So if we would classify VS Code as a "tool" then it has the ambition to support both.

Yes, I am aware that tools can handle them generically in some sense. But that doesn't mean they follow the module: around the project. I am not an expert on all of the tools. I only help build eslint-plugin-jsdoc according to what the standards (in this case, TypeScript, Closure, and jsdoc, advertise themselves as supporting, and when necessary and time is available, digging into their source code to find what they support).

You are welcome to try permissive mode if you really wish to use all of the features, but as there is no official "permissive" mode to go by, there are no guarantees we will maintain that to continue to work for your particular needs or even that we will indefinitely maintain it if circumstances change to make it hard to maintain. But right now, it isn't hard for us to offer it, so if you don't mind the risk that it won't work suitably for tooling, then go ahead with that unless you come to find a need to restrict your project. You might look at https://www.typescriptlang.org/docs/handbook/jsdoc-supported-types.html , for example, to see that TypeScript doesn't "support" certain tags, but that doesn't mean all of its tools can't be made to accept them in some sense either. You have to investigate that yourself.

[thernstig]

I understand I might have asked a bit too much here, but I found it valuable as a large portion of users use VS Code with the built-in JSDoc and thus might stumble on this. I will try typescript mode to see what it does for us. Thanks.

[brettz9]

Your questions were fine and understandable; I just want to make clear about not going on too much here in case you are still in doubt about it.

And I should say I am sometimes personally in doubt about it despite working on such a project! It isn't easy when the project we are targeting is not completely dead, but is not very active or able to be responsive to questions, and another project with a different but overlapping scope is active and the two are in a relative stasis with it. But yeah, "typescript" is probably the way to go, at least if you don't want to be disappointed with TypeScript not doing what you think it should with the syntax if you end up using it (though tools like typedoc at least will still pass your custom tags through).

We could switch from the default at some point, e.g., if the documentation tool jsdoc officially dies, but since this is eslint-plugin-jsdoc, I think it makes sense to keep that as the default for now.

[brettz9]

Btw, one problem I'm running into with typedoc/typescript is that one might have to refactor even plain JavaScript to get things to work. It is not perfectly intelligent (or it is overly opinionated) in requiring things like initializing destructured values, not being able to overwrite a property in some cases as it corrupts the type, etc.

Using the jsdoc documentation tool comes at the cost of not getting all of the type validation, and presumably in not using TS-friendly jsdoc, one might lose the autocomplete/tooltips (though ternjs may help), etc., but it also doesn't require you to change your JavaScript to suit the tool.