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

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

About this issue

Original URL
State: closed
Created 5 years ago
Reactions: 3
Comments: 17 (5 by maintainers)

Most upvoted comments

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}'?

+27

DanielRosenwasser on Jan 29, 2020

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.

+13

arthurgeron on Oct 20, 2019

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.

techieshark on Aug 30, 2020

Not to necrobump this. but @DanielRosenwasser has made some good suggestions here. This issue is still present, and confusing initially, for folks coming from Flow. Hope Daniel’s ideas are implemented at some point in the future.

arjun-menon on Jun 10, 2022

@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

FabianLauer on Mar 5, 2019

Another example case where I ran into this just now was with the following code:

const foo: string? = process.env['FOO'];

My brain was thinking of optional parameter syntax (though got that wrong too) when I ran into this:

https://www.typescriptlang.org/docs/handbook/2/functions.html#optional-parameters

(I’m also a little confused/unsure as to why it thinks the type is string | null here, which sort of led me on a little bit of a rabbithole since the type I was expecting based on how optional parameters work was string | undefined)

0xdevalias on Jul 1, 2022

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

Quelklef on Jun 30, 2020

0akl3y on Jan 28, 2020