Two JSdoc parsing fixes (microsoft#22705)

* Correctly parse JSDoc type *=

* Allow `markdown` quoted param names in JSDoc

* Add tests and update baselines

* Get correct span for the type '*'

* Fix whitespace lint

* Add unbracketed type test

Author: sandersn

src/compiler/parser.ts

@@ -2203,9 +2203,14 @@ namespace ts {
             return finishNode(node);
         }
 
-        function parseJSDocAllType(): JSDocAllType {
+        function parseJSDocAllType(postFixEquals: boolean): JSDocAllType | JSDocOptionalType {
             const result = createNode(SyntaxKind.JSDocAllType) as JSDocAllType;
-            nextToken();
+            if (postFixEquals) {
+                return createJSDocPostfixType(SyntaxKind.JSDocOptionalType, result) as JSDocOptionalType;
+            }
+            else {
+                nextToken();
+            }
             return finishNode(result);
         }
 
@@ -2740,7 +2745,9 @@ namespace ts {
                     // If these are followed by a dot, then parse these out as a dotted type reference instead.
                     return tryParse(parseKeywordAndNoDot) || parseTypeReference();
                 case SyntaxKind.AsteriskToken:
-                    return parseJSDocAllType();
+                    return parseJSDocAllType(/*postfixEquals*/ false);
+                case SyntaxKind.AsteriskEqualsToken:
+                    return parseJSDocAllType(/*postfixEquals*/ true);
                 case SyntaxKind.QuestionToken:
                     return parseJSDocUnknownOrNullableType();
                 case SyntaxKind.FunctionKeyword:
@@ -6496,6 +6503,10 @@ namespace ts {
                 }
 
                 function parseBracketNameInPropertyAndParamTag(): { name: EntityName, isBracketed: boolean } {
+                    if (token() === SyntaxKind.NoSubstitutionTemplateLiteral) {
+                        // a markdown-quoted name: `arg` is not legal jsdoc, but occurs in the wild
+                        return { name: createIdentifier(/*isIdentifier*/ true), isBracketed: false };
+                    }
                     // Looking for something like '[foo]', 'foo', '[foo.bar]' or 'foo.bar'
                     const isBracketed = parseOptional(SyntaxKind.OpenBracketToken);
                     const name = parseJSDocEntityName();

src/compiler/scanner.ts

@@ -1974,6 +1974,13 @@ namespace ts {
                     return token = SyntaxKind.CommaToken;
                 case CharacterCodes.dot:
                     return token = SyntaxKind.DotToken;
+                case CharacterCodes.backtick:
+                    while (pos < end && text.charCodeAt(pos) !== CharacterCodes.backtick) {
+                        pos++;
+                    }
+                    tokenValue = text.substring(tokenPos + 1, pos);
+                    pos++;
+                    return token = SyntaxKind.NoSubstitutionTemplateLiteral;
             }
 
             if (isIdentifierStart(ch, ScriptTarget.Latest)) {

src/compiler/types.ts

@@ -73,6 +73,7 @@ namespace ts {
         | SyntaxKind.CommaToken
         | SyntaxKind.DotToken
         | SyntaxKind.Identifier
+        | SyntaxKind.NoSubstitutionTemplateLiteral
         | SyntaxKind.Unknown;
 
     export type JsxTokenSyntaxKind =
@@ -84,7 +85,7 @@ namespace ts {
         | SyntaxKind.OpenBraceToken
         | SyntaxKind.LessThanToken;
 
-    // token > SyntaxKind.Identifer => token is a keyword
+    // token > SyntaxKind.Identifier => token is a keyword
     // Also, If you add a new SyntaxKind be sure to keep the `Markers` section at the bottom in sync
     export const enum SyntaxKind {
         Unknown,

tests/baselines/reference/api/tsserverlibrary.d.ts

@@ -59,7 +59,7 @@ declare namespace ts {
         pos: number;
         end: number;
     }
-    type JsDocSyntaxKind = SyntaxKind.EndOfFileToken | SyntaxKind.WhitespaceTrivia | SyntaxKind.AtToken | SyntaxKind.NewLineTrivia | SyntaxKind.AsteriskToken | SyntaxKind.OpenBraceToken | SyntaxKind.CloseBraceToken | SyntaxKind.LessThanToken | SyntaxKind.OpenBracketToken | SyntaxKind.CloseBracketToken | SyntaxKind.EqualsToken | SyntaxKind.CommaToken | SyntaxKind.DotToken | SyntaxKind.Identifier | SyntaxKind.Unknown;
+    type JsDocSyntaxKind = SyntaxKind.EndOfFileToken | SyntaxKind.WhitespaceTrivia | SyntaxKind.AtToken | SyntaxKind.NewLineTrivia | SyntaxKind.AsteriskToken | SyntaxKind.OpenBraceToken | SyntaxKind.CloseBraceToken | SyntaxKind.LessThanToken | SyntaxKind.OpenBracketToken | SyntaxKind.CloseBracketToken | SyntaxKind.EqualsToken | SyntaxKind.CommaToken | SyntaxKind.DotToken | SyntaxKind.Identifier | SyntaxKind.NoSubstitutionTemplateLiteral | SyntaxKind.Unknown;
     type JsxTokenSyntaxKind = SyntaxKind.LessThanSlashToken | SyntaxKind.EndOfFileToken | SyntaxKind.ConflictMarkerTrivia | SyntaxKind.JsxText | SyntaxKind.JsxTextAllWhiteSpaces | SyntaxKind.OpenBraceToken | SyntaxKind.LessThanToken;
     enum SyntaxKind {
         Unknown = 0,

tests/baselines/reference/api/typescript.d.ts

@@ -59,7 +59,7 @@ declare namespace ts {
         pos: number;
         end: number;
     }
-    type JsDocSyntaxKind = SyntaxKind.EndOfFileToken | SyntaxKind.WhitespaceTrivia | SyntaxKind.AtToken | SyntaxKind.NewLineTrivia | SyntaxKind.AsteriskToken | SyntaxKind.OpenBraceToken | SyntaxKind.CloseBraceToken | SyntaxKind.LessThanToken | SyntaxKind.OpenBracketToken | SyntaxKind.CloseBracketToken | SyntaxKind.EqualsToken | SyntaxKind.CommaToken | SyntaxKind.DotToken | SyntaxKind.Identifier | SyntaxKind.Unknown;
+    type JsDocSyntaxKind = SyntaxKind.EndOfFileToken | SyntaxKind.WhitespaceTrivia | SyntaxKind.AtToken | SyntaxKind.NewLineTrivia | SyntaxKind.AsteriskToken | SyntaxKind.OpenBraceToken | SyntaxKind.CloseBraceToken | SyntaxKind.LessThanToken | SyntaxKind.OpenBracketToken | SyntaxKind.CloseBracketToken | SyntaxKind.EqualsToken | SyntaxKind.CommaToken | SyntaxKind.DotToken | SyntaxKind.Identifier | SyntaxKind.NoSubstitutionTemplateLiteral | SyntaxKind.Unknown;
     type JsxTokenSyntaxKind = SyntaxKind.LessThanSlashToken | SyntaxKind.EndOfFileToken | SyntaxKind.ConflictMarkerTrivia | SyntaxKind.JsxText | SyntaxKind.JsxTextAllWhiteSpaces | SyntaxKind.OpenBraceToken | SyntaxKind.LessThanToken;
     enum SyntaxKind {
         Unknown = 0,

tests/baselines/reference/jsdocParseBackquotedParamName.symbols

@@ -0,0 +1,20 @@
+=== tests/cases/conformance/jsdoc/a.js ===
+/**
+ * @param {string=} `args`
+ * @param `bwarg` {?number?}
+ */
+function f(args, bwarg) {
+>f : Symbol(f, Decl(a.js, 0, 0))
+>args : Symbol(args, Decl(a.js, 4, 11))
+>bwarg : Symbol(bwarg, Decl(a.js, 4, 16))
+}
+
+=== tests/cases/conformance/jsdoc/ts.ts ===
+/**
+ * @param `arg` - this is fine
+ */
+function g(arg: string) {
+>g : Symbol(g, Decl(ts.ts, 0, 0))
+>arg : Symbol(arg, Decl(ts.ts, 3, 11))
+}
+

tests/baselines/reference/jsdocParseBackquotedParamName.types

@@ -0,0 +1,20 @@
+=== tests/cases/conformance/jsdoc/a.js ===
+/**
+ * @param {string=} `args`
+ * @param `bwarg` {?number?}
+ */
+function f(args, bwarg) {
+>f : (args?: string | undefined, bwarg: number | null) => void
+>args : string | undefined
+>bwarg : number | null
+}
+
+=== tests/cases/conformance/jsdoc/ts.ts ===
+/**
+ * @param `arg` - this is fine
+ */
+function g(arg: string) {
+>g : (arg: string) => void
+>arg : string
+}
+

tests/baselines/reference/jsdocParseStarEquals.symbols

@@ -0,0 +1,14 @@
+=== tests/cases/conformance/jsdoc/a.js ===
+/** @param {...*=} args
+    @return {*=} */
+function f(...args) {
+>f : Symbol(f, Decl(a.js, 0, 0))
+>args : Symbol(args, Decl(a.js, 2, 11))
+
+    return null
+}
+
+/** @type *= */
+var x;
+>x : Symbol(x, Decl(a.js, 7, 3))
+

tests/baselines/reference/jsdocParseStarEquals.types

@@ -0,0 +1,15 @@
+=== tests/cases/conformance/jsdoc/a.js ===
+/** @param {...*=} args
+    @return {*=} */
+function f(...args) {
+>f : (...args: any[]) => any
+>args : any[]
+
+    return null
+>null : null
+}
+
+/** @type *= */
+var x;
+>x : any
+

tests/cases/conformance/jsdoc/jsdocParseBackquotedParamName.ts

@@ -0,0 +1,20 @@
+// @noEmit: true
+// @allowJs: true
+// @checkJs: true
+// @strict: true
+// @Filename: a.js
+
+/**
+ * @param {string=} `args`
+ * @param `bwarg` {?number?}
+ */
+function f(args, bwarg) {
+}
+
+// @Filename: ts.ts
+
+/**
+ * @param `arg` - this is fine
+ */
+function g(arg: string) {
+}

tests/cases/conformance/jsdoc/jsdocParseStarEquals.ts

@@ -0,0 +1,14 @@
+// @noEmit: true
+// @allowJs: true
+// @checkJs: true
+// @strict: true
+// @Filename: a.js
+
+/** @param {...*=} args
+    @return {*=} */
+function f(...args) {
+    return null
+}
+
+/** @type *= */
+var x;