Merge pull request #10399 from Microsoft/jsdoc-never-undefined-null-types

JSDoc supports null, undefined and never types

src/compiler/checker.ts

@@ -5552,6 +5552,12 @@ namespace ts {
                     return nullType;
                 case SyntaxKind.NeverKeyword:
                     return neverType;
+                case SyntaxKind.JSDocNullKeyword:
+                    return nullType;
+                case SyntaxKind.JSDocUndefinedKeyword:
+                    return undefinedType;
+                case SyntaxKind.JSDocNeverKeyword:
+                    return neverType;
                 case SyntaxKind.ThisType:
                 case SyntaxKind.ThisKeyword:
                     return getTypeFromThisTypeNode(node);

src/compiler/parser.ts

@@ -5893,6 +5893,9 @@ namespace ts {
                     case SyntaxKind.BooleanKeyword:
                     case SyntaxKind.SymbolKeyword:
                     case SyntaxKind.VoidKeyword:
+                    case SyntaxKind.NullKeyword:
+                    case SyntaxKind.UndefinedKeyword:
+                    case SyntaxKind.NeverKeyword:
                         return parseTokenNode<JSDocType>();
                     case SyntaxKind.StringLiteral:
                     case SyntaxKind.NumericLiteral:

src/compiler/types.ts

@@ -351,6 +351,9 @@ namespace ts {
         JSDocPropertyTag,
         JSDocTypeLiteral,
         JSDocLiteralType,
+        JSDocNullKeyword,
+        JSDocUndefinedKeyword,
+        JSDocNeverKeyword,
 
         // Synthesized list
         SyntaxList,
@@ -383,7 +386,7 @@ namespace ts {
         FirstJSDocNode = JSDocTypeExpression,
         LastJSDocNode = JSDocLiteralType,
         FirstJSDocTagNode = JSDocComment,
-        LastJSDocTagNode = JSDocLiteralType
+        LastJSDocTagNode = JSDocNeverKeyword
     }
 
     export const enum NodeFlags {

src/harness/unittests/jsDocParsing.ts

@@ -767,16 +767,9 @@ namespace ts {
                     parsesCorrectly(
                         "{null}",
                         `{
-    "kind": "JSDocTypeReference",
+    "kind": "NullKeyword",
     "pos": 1,
-    "end": 5,
-    "name": {
-        "kind": "Identifier",
-        "pos": 1,
-        "end": 5,
-        "originalKeywordKind": "NullKeyword",
-        "text": "null"
-    }
+    "end": 5
 }`);
                 });
 
@@ -784,16 +777,9 @@ namespace ts {
                     parsesCorrectly(
                         "{undefined}",
                         `{
-    "kind": "JSDocTypeReference",
+    "kind": "UndefinedKeyword",
     "pos": 1,
-    "end": 10,
-    "name": {
-        "kind": "Identifier",
-        "pos": 1,
-        "end": 10,
-        "originalKeywordKind": "UndefinedKeyword",
-        "text": "undefined"
-    }
+    "end": 10
 }`);
                 });
 
@@ -2379,4 +2365,4 @@ namespace ts {
             });
         });
     });
-}
+}

tests/baselines/reference/jsdocNeverUndefinedNull.js

@@ -0,0 +1,20 @@
+//// [in.js]
+/**
+ * @param {never} p1
+ * @param {undefined} p2
+ * @param {null} p3
+ * @returns {void} nothing
+ */
+function f(p1, p2, p3) {
+}
+
+
+//// [out.js]
+/**
+ * @param {never} p1
+ * @param {undefined} p2
+ * @param {null} p3
+ * @returns {void} nothing
+ */
+function f(p1, p2, p3) {
+}

tests/baselines/reference/jsdocNeverUndefinedNull.symbols

@@ -0,0 +1,14 @@
+=== tests/cases/conformance/jsdoc/in.js ===
+/**
+ * @param {never} p1
+ * @param {undefined} p2
+ * @param {null} p3
+ * @returns {void} nothing
+ */
+function f(p1, p2, p3) {
+>f : Symbol(f, Decl(in.js, 0, 0))
+>p1 : Symbol(p1, Decl(in.js, 6, 11))
+>p2 : Symbol(p2, Decl(in.js, 6, 14))
+>p3 : Symbol(p3, Decl(in.js, 6, 18))
+}
+

tests/baselines/reference/jsdocNeverUndefinedNull.types

@@ -0,0 +1,14 @@
+=== tests/cases/conformance/jsdoc/in.js ===
+/**
+ * @param {never} p1
+ * @param {undefined} p2
+ * @param {null} p3
+ * @returns {void} nothing
+ */
+function f(p1, p2, p3) {
+>f : (p1: never, p2: undefined, p3: null) => void
+>p1 : never
+>p2 : undefined
+>p3 : null
+}
+

tests/cases/conformance/jsdoc/jsdocNeverUndefinedNull.ts

@@ -0,0 +1,11 @@
+// @allowJs: true
+// @filename: in.js
+// @out: out.js
+/**
+ * @param {never} p1
+ * @param {undefined} p2
+ * @param {null} p3
+ * @returns {void} nothing
+ */
+function f(p1, p2, p3) {
+}

tests/cases/fourslash/jsdocNullableUnion.ts

@@ -0,0 +1,23 @@
+///<reference path="fourslash.ts" />
+// @allowNonTsExtensions: true
+// @Filename: Foo.js
+////
+//// * @param {never | {x: string}} p1
+//// * @param {undefined | {y: number}} p2
+//// * @param {null | {z: boolean}} p3
+//// * @returns {void} nothing
+//// */
+////function f(p1, p2, p3) {
+////    p1./*1*/
+////    p2./*2*/
+////    p3./*3*/
+////}
+
+goTo.marker('1');
+verify.memberListContains("x");
+
+goTo.marker('2');
+verify.memberListContains("y");
+
+goTo.marker('3');
+verify.memberListContains("z");