Option to disable JsDoc parsing

[nickserv]

A description of the problem you're trying to solve

JsDoc comment parsing is very useful when typechecking JavaScript files with allowJs and checkJs, but sometimes it gets in the way of migrating existing JsDoc files to TypeScript, especially when the types are incorrect or use features not supported by the TypeScript compiler. The main goal of this is to make it easier to type existing packages using JsDoc (incorrectly).

For example, I'm contributing declaration files to a package that is currently using JsDoc types with some mismatching parameter names and syntax errors. As a result, I get a large number of TypeScript compiler errors because of the invalid syntax and conflicts with my more up to date TypeScript typings. This error and consistency checking is good default behavior, but in this case I want to override or disable the parsed JsDoc types so I can contribute typings without making unrelated changes to the package, like porting files to TypeScript (in which case I could just use TypeDoc) or removing JsDoc comments (which are needed for documentation and can be fixed later). If I disabled checkJs, I would lose TypeScript's type checking using my declaration files against the original JS sources, and it would be difficult to verify them. This would be especially useful for DefinitelyTyped, since you can't adjust the syntax of the original source code's JsDoc comments in a separate package.

An overview of the suggested solution

A compiler option named noJsdoc or disableJsdoc, defaulting to false. When enabled, JsDoc comments are not parsed and do not create type errors or affect the types of JavaScript code.

Examples of how the suggestion would work in various places

If this could live in the tsconfig, it would be easy for external tools like editor plugins to determine if they should inspect JsDoc comments for TypeScript integration, though this could be handled by the compiler or language service in most cases.

Code example

index.js

Original package source with inaccurate JsDoc types. I'm looking for a way to ignore them without modifying the original file, as it lives in someone else's package that I'm writing a typing package for.

/**
 * @type {string}
 */
export const defaultOptions = { name: "Foo" };

index.d.ts

TypeScript declaration file for index.js. Note that the type is more accurate than the JsDoc type and needs to replace it, but TypeScript compiler will fail on the JsDoc types being incompatible with the declaration file's types. I am suggesting a way for TypeScript to ignore the JsDoc types when using this TypeScript declaration file.

export const defaultOptions: { name: string };

tsconfig.json

TypeScript config for the declaration package file. Note that the new noJsdoc option is enabled, and TypeScript is only being used as a typechecker (no files are generated).

{
  "compilerOptions": {
    "allowJs": true,
    "checkJs": true,
    "noEmit": true,
    "noJsdoc": true
  }
}

[mhegazy]

I am a bit confused here. first not sure i understand where the declaration file generation fits in, since a .d.ts file is not generated from a .js file, only from a .ts file.
Second, disabling parsing of jsdoc means you get no types from them either. or you want the types but not the errors?
Do you have a sample in mind we can look at?

[nickserv]

first not sure i understand where the declaration file generation fits in, since a .d.ts file is not generated from a .js file, only from a .ts file

My use case is writing declaration files (.d.ts) for a pure JS package by hand, so I'm not generating them and I'm using noEmit. I'm only testing that the declaration file is accurate against the JS source code.

Second, disabling parsing of jsdoc means you get no types from them either. or you want the types but not the errors?

I want no types and no error (the compiler acts as if it had no JsDoc support). This way I can add declaration files for packages with broken or conflicting JsDoc types without modifying the sources.

Do you have a sample in mind we can look at?

Sorry I'm still working on the typings and haven't pushed them yet, but if you want to see the original JS and JsDoc package it's selectorator.

Referring to my examples in this issue, imagine that index.js is a source package I can't modify and index.d.ts is a declaration file I'm contributing to DefinitelyTyped. The goal is to get the TypeScript compiler to pass on the JS file and my declaration without modifying the JS file, even if the JS file's JsDoc type is completely incompatible with TypeScript's type.

[nickserv]

I added descriptions to my code examples. Hopefully it will be more clear now but please let me know if I can clarify anything else.

[sandersn]

That makes more sense to me. I think what you're trying to do is

1. Use a .d.ts file to give types to declarations in a .js file (ignoring existing jsdoc comments if needed).
2. Check the .js file with these new types, and report any errors as usual.

If that's the case, then the reason we hadn't considered this feature yet is that we think most Javascript users prefer JSDoc over declarations in a separate file, and we expect that most code bases can be modified, as long as it's only in the comments.

I might also have misunderstood, and it could be that you want to:

1. Check the .js file, ignoring jsdoc comments.
2. Compare the types of the .js file with the types of the matching declarations in the .d.ts file, and report where they don't match.

I don't think we support anything like this scenario right now.

[nickserv]

The former use case is what I'm trying to do (I want to completely avoid the JSDoc types). However, I would prefer not to adjust the JSDoc comments as I want to add declarations to this package without providing other changes (like changing JSDoc generated document) to make it easier to merge the declarations into the same package. If the package author did not want to make any changes for TypeScript, I would be unable to create declarations for this package because the types would be invalid against the JSDoc comments (if I'm understanding checkJs correctly). This would prevent me from using TypeScript in a package that consumes this package with the JSDoc comments.

I think this feature could still be useful, but I'm curious about the recommended JSDoc usage. Does it have full support for all TypeScript types in declaration files in a way that is back compatible with JSDoc?

[mhegazy]

The former use case is what I'm trying to do (I want to completely avoid the JSDoc types). However, I would prefer not to adjust the JSDoc comments as I want to add declarations to this package without providing other changes (like changing JSDoc generated document) to make it easier to merge the declarations into the same package.

This is the part I keep getting tripped on in this issue; let me reiterate to make sure i understand, first you want the types not to be infered from the JSDoc, and second you want them to be picked up from the .d.ts instead. is that correct?

the second is not supported and is much bigger request, so disabling the use of JSDoc as source of types will not take you far.

Relevant discussion in #7661

I would be unable to create declarations for this package because the types would be invalid against the JSDoc comments (if I'm understanding checkJs correctly).

I do not think this is true. the compiler always picks a .d.ts file before a .js file. so if you have a declaration file for the package, the compiler will not look at the .js file, nor would it look at the JSDoc comments from this file.. it only looks at the .d.ts file.

So you could author your .d.ts file and not touch the .js file at all.

This would prevent me from using TypeScript in a package that consumes this package with the JSDoc comments.

Again, that is not true.

I think this feature could still be useful, but I'm curious about the recommended JSDoc usage. Does it have full support for all TypeScript types in declaration files in a way that is back compatible with JSDoc?

See https://github.com/Microsoft/TypeScript/wiki/Type-Checking-JavaScript-Files and https://github.com/Microsoft/TypeScript/wiki/JsDoc-support-in-JavaScript for more details.

[nickserv]

Thanks, I appreciate your clarification.

first you want the types not to be infered from the JSDoc, and second you want them to be picked up from the .d.ts instead. is that correct?

I want types to be picked up from .d.ts while also verifying their accuracy against the JS files (excluding JSDoc comments) in development. I was under the impression that this is possible with tsc and checkJs, but the invalid JSDoc comments from the original JS files get in the way of the type checking. checkJS works great when I remove the JSDoc comments, and I'd like a way to get a similar workflow without removing them.

the compiler always picks a .d.ts file before a .js file

tsc is checking both .d.ts and .js files when I use checkJs, allowJs, and noEmit (without declare module or namespaces in my declaration file). I have a single index.d.ts for a package with multiple JS files including one named index.js. Does TypeScript only type check both declaration and source files when the files are in the same package (in which case the JSDoc comments would only be an issue in development), or is this an incorrect setup? As an alternative to porting the package sources to TypeScript, should I instead move my index.d.ts types to the JSDoc comments or DefinitelyTyped?

[mhegazy]

I want types to be picked up from .d.ts while also verifying their accuracy against the JS files (excluding JSDoc comments) in development.

That is a feature request. i suggest filing a new issue for that, since this one is a bit vague and has a lot of unrelated details. It is worth noting that while this is a valuable feature, the problem is not simple. see #7661 for more details. This is actually the topic of a few research papers (see https://cs.au.dk/~amoeller/papers/tscheck/paper.pdf). It is really hard for the compiler, in the general case, to detect the structure of a .js file let a side comparing it to a .d.ts file without creating too much noise.

checkJS works great when I remove the JSDoc comments, and I'd like a way to get a similar workflow without removing them.

not sure what you mean there, since --checkJs does not use the info from the .d.ts file in any way.

tsc is checking both .d.ts and .js files when I use checkJs, allowJs, and noEmit (without declare module or namespaces in my declaration file). I have a single index.d.ts for a package with multiple JS files including one named index.js.

the two files are "included" in your compilation, but the types in the .d.ts are not used to guide any checking in the .js file. again this is not how the feature works. the compiler will check both files for correctness independently.

If you include that module in another module, then only the .d.ts file will be picked up. the .js file is ignored.

Does TypeScript only type check both declaration and source files when the files are in the same package (in which case the JSDoc comments would only be an issue in development), or is this an incorrect setup?

I really think you are confusing what checkJs does. it does not do that, you can take my word for it..

As an alternative to porting the package sources to TypeScript, should I instead move my index.d.ts types to the JSDoc comments or DefinitelyTyped?

These are two different problems i contend:

1. I want to give users of this package a well typed API to program against without chaining the package implementation.. For that add a .d.ts file, no changes needed to the .js file, JSDoc comments here have no impact what so ever. checkJs is not even applicable here..

2. I am working on this .js file, and i want the TS compiler to help me out, but i do not want to change it to .ts file. For that use --checkJs, types within your .js file are picked up from JSDoc, the .d.ts file here is not applicable.

Again, the problem of I have a .d.ts and a matching .js file and want the compiler to verify they match is a third problem, and i would log a new issue for that as i noted in my comment earlier.

[nickserv]

Sorry for the confusion, I thought checkJs checked types across declaration files and JS files all along. As a result I'm going to take a different approach, and I don't need this feature because I can either disable checkJs or fix the types in JSDoc direcly. Thanks for all your help.