Typescript: Error message related to JSDoc for non-JSDoc syntax error

[FabianLauer]

TypeScript Version:

• 3.4.0-dev.20190130
• 3.2.4

Search Terms:

• ts8020
• "jsdoc types can only be used"
• "JSDoc types can only be used inside documentation comments"

Code

function isString(str: string): str is string! {
  return typeof str === 'string';
}

Expected behavior:

Error message should not mention JSDoc syntax. IMHO it should be TS1144: '{' or ';' expected., which is the case with this code for example:

function isString(str: string): str is string? {
  return typeof str === 'string';
}

Actual behavior:

Error message states that this is JSDoc syntax (am not sure it even is). Full output of tsc:

> tsc test.ts
test.ts:1:40 - error TS8020: JSDoc types can only be used inside documentation comments.

1 function isString(str: string): str is string! {
                                         ~~~~~~~


Found 1 error.

Playground Link:
here

Related Issues:

• PR #17250

[pbrahmbhatt3]

can i work on it?

[DanielRosenwasser]

I don't understand why the suggested error message is better. Maybe we shouldn't mention JSDoc to begin with and that's the issue. The error message should probably be something like

Adding a postix '!' to the end of a type is not valid TypeScript syntax.

and

Adding a postix '?' to the end of a type is not valid TypeScript syntax. Did you mean to write 'Foo | null | undefined'?

Generalized to

Adding a postix '{0}' to the end of a type is not valid TypeScript syntax. Did you mean to write '{1}'?

[FabianLauer]

@DanielRosenwasser My words exactly, JSDoc shouldn't be mentioned here 🙂

@pbrahmbhatt3 I'm not sure if your PR fixes the same bug that this issue is about

[pbrahmbhatt3]

Any suggestions on fixing this issue @FabianLauer

[FabianLauer]

I think besides type guards this can also be repdocued in type assertions. Any expression such as this...

1 as any!;

... seems to produce TS8020 as well. Playground example here.

[arthurgeron]

when I mistakenly declared a function parameter as options:? ParseUrlOptions I also got the JSDoc types can only be used inside documentation comments error message which was very confusing to me, I don't think JSDoc should be mentioned instead of the actual error.

[0akl3y]

+1

[Quelklef]

+1 to removing a mention of JSDoc (or lessening it); I had gotten this error from typing let val: Type! instead of let val!: Type; the reference to JSDoc confused me until I found this issue.

[techieshark]

Yeah coming from Flow (which uses ? for Maybe types), I found the mention of JSDoc confusing.

+1 for saying which character is unexpected and perhaps a "did you mean" comment like @DanielRosenwasser suggests above.

[hmanalai]

I would like to work on this issue if no one else is already.

[a-tarasyuk]

@DanielRosenwasser I'm curious, is it ok to extend the parser with this kind of message? Or is it better to avoid adding error handling to the parser to avoid problems with incremental builds?

[DanielRosenwasser]

Do you mean incremental parsing issues? I would hope this doesn't affect either, but the change should be at the same place where the current message is probably issued.

[a-tarasyuk]

Do you mean incremental parsing issues?

Yes