Fix jsdoc comment parsing initial state (microsoft#36661)

* Fix jsdoc comment parsing initial state

Jsdoc comment parsing can be invoked in two modes:

1. top-level parsing, for comments not inside a tag.
2. tag parsing, for comment that occur after the semantic parts of a
tag.

Top-level parsing skips an initial * because it assumes that it is starting
at the very beginning of a JSDoc comment. Tag parsing does not.

The two modes are distinguished by an optional second parameter named
`margin`. When `margin` is provided, it provides an initial indent used
for comment alignment.

Previously, the check for `margin` was a truthy check `if (margin)`.
This check incorrectly treats `margin=""` the same as
`margin=undefined`.

This PR changes the check to `if (margin !== undefined)`, which
correctly treats `margin=""` the same as `margin="    "`.

* Fixes for broken tests

1. Use SawAsterisk start state.
2. @template needs to skip asterisk in addition to whitespace while
parsing type parameter names.

* undo code move

Author: sandersn

src/compiler/parser.ts

@@ -7017,10 +7017,12 @@ namespace ts {
                         comments.push(text);
                         indent += text.length;
                     }
-                    if (initialMargin) {
+                    if (initialMargin !== undefined) {
                         // jump straight to saving comments if there is some initial indentation
-                        pushComment(initialMargin);
-                        state = JSDocState.SavingComments;
+                        if (initialMargin !== "") {
+                            pushComment(initialMargin);
+                        }
+                        state = JSDocState.SawAsterisk;
                     }
                     let tok = token() as JSDocSyntaxKind;
                     loop: while (true) {
@@ -7558,7 +7560,7 @@ namespace ts {
                         const typeParameter = <TypeParameterDeclaration>createNode(SyntaxKind.TypeParameter);
                         typeParameter.name = parseJSDocIdentifierName(Diagnostics.Unexpected_token_A_type_parameter_name_was_expected_without_curly_braces);
                         finishNode(typeParameter);
-                        skipWhitespace();
+                        skipWhitespaceOrAsterisk();
                         typeParameters.push(typeParameter);
                     } while (parseOptionalJsdoc(SyntaxKind.CommaToken));
 

tests/baselines/reference/quickInfoDisplayPartsParameters.baseline

@@ -2,13 +2,13 @@
   {
     "marker": {
       "fileName": "/tests/cases/fourslash/quickInfoDisplayPartsParameters.ts",
-      "position": 9
+      "position": 33
     },
     "quickInfo": {
       "kind": "function",
       "kindModifiers": "",
       "textSpan": {
-        "start": 9,
+        "start": 33,
         "length": 3
       },
       "displayParts": [
@@ -153,19 +153,25 @@
           "kind": "keyword"
         }
       ],
-      "documentation": []
+      "documentation": [],
+      "tags": [
+        {
+          "name": "return",
+          "text": "*crunch*"
+        }
+      ]
     }
   },
   {
     "marker": {
       "fileName": "/tests/cases/fourslash/quickInfoDisplayPartsParameters.ts",
-      "position": 13
+      "position": 37
     },
     "quickInfo": {
       "kind": "parameter",
       "kindModifiers": "",
       "textSpan": {
-        "start": 13,
+        "start": 37,
         "length": 5
       },
       "displayParts": [
@@ -208,13 +214,13 @@
   {
     "marker": {
       "fileName": "/tests/cases/fourslash/quickInfoDisplayPartsParameters.ts",
-      "position": 28
+      "position": 52
     },
     "quickInfo": {
       "kind": "parameter",
       "kindModifiers": "",
       "textSpan": {
-        "start": 28,
+        "start": 52,
         "length": 13
       },
       "displayParts": [
@@ -257,13 +263,13 @@
   {
     "marker": {
       "fileName": "/tests/cases/fourslash/quickInfoDisplayPartsParameters.ts",
-      "position": 52
+      "position": 76
     },
     "quickInfo": {
       "kind": "parameter",
       "kindModifiers": "",
       "textSpan": {
-        "start": 52,
+        "start": 76,
         "length": 20
       },
       "displayParts": [
@@ -306,13 +312,13 @@
   {
     "marker": {
       "fileName": "/tests/cases/fourslash/quickInfoDisplayPartsParameters.ts",
-      "position": 87
+      "position": 111
     },
     "quickInfo": {
       "kind": "parameter",
       "kindModifiers": "",
       "textSpan": {
-        "start": 87,
+        "start": 111,
         "length": 9
       },
       "displayParts": [
@@ -363,13 +369,13 @@
   {
     "marker": {
       "fileName": "/tests/cases/fourslash/quickInfoDisplayPartsParameters.ts",
-      "position": 114
+      "position": 138
     },
     "quickInfo": {
       "kind": "parameter",
       "kindModifiers": "",
       "textSpan": {
-        "start": 114,
+        "start": 138,
         "length": 5
       },
       "displayParts": [
@@ -412,13 +418,13 @@
   {
     "marker": {
       "fileName": "/tests/cases/fourslash/quickInfoDisplayPartsParameters.ts",
-      "position": 135
+      "position": 159
     },
     "quickInfo": {
       "kind": "parameter",
       "kindModifiers": "",
       "textSpan": {
-        "start": 135,
+        "start": 159,
         "length": 13
       },
       "displayParts": [
@@ -461,13 +467,13 @@
   {
     "marker": {
       "fileName": "/tests/cases/fourslash/quickInfoDisplayPartsParameters.ts",
-      "position": 164
+      "position": 188
     },
     "quickInfo": {
       "kind": "parameter",
       "kindModifiers": "",
       "textSpan": {
-        "start": 164,
+        "start": 188,
         "length": 20
       },
       "displayParts": [
@@ -510,13 +516,13 @@
   {
     "marker": {
       "fileName": "/tests/cases/fourslash/quickInfoDisplayPartsParameters.ts",
-      "position": 200
+      "position": 224
     },
     "quickInfo": {
       "kind": "parameter",
       "kindModifiers": "",
       "textSpan": {
-        "start": 200,
+        "start": 224,
         "length": 9
       },
       "displayParts": [

tests/cases/fourslash/quickInfoDisplayPartsParameters.ts

@@ -1,10 +1,11 @@
 /// <reference path='fourslash.ts'/>
 
-////function /*1*/foo(/*2*/param: string, /*3*/optionalParam?: string, /*4*/paramWithInitializer = "hello", .../*5*/restParam: string[]) {
-////    /*6*/param = "Hello";
-////    /*7*/optionalParam = "World";
-////    /*8*/paramWithInitializer = "Hello";
-////    /*9*/restParam[0] = "World";
-////}
+//// /** @return *crunch* */
+//// function /*1*/foo(/*2*/param: string, /*3*/optionalParam?: string, /*4*/paramWithInitializer = "hello", .../*5*/restParam: string[]) {
+////     /*6*/param = "Hello";
+////     /*7*/optionalParam = "World";
+////     /*8*/paramWithInitializer = "Hello";
+////     /*9*/restParam[0] = "World";
+//// }
 
-verify.baselineQuickInfo();
+verify.baselineQuickInfo();