Rename SyntaxKind.JSDocComment -> JSDoc (#44416)

* Rename SyntaxKind.JSDocComment -> JSDoc

Early on, I made the mistake of using the syntax kind JSDocComment for
the type JSDoc. This arose because
I hadn't decided on the terminology of "jsdoc" for the C-style comment
that is attached to a declaration. "comment"
for the text that follows a tag. By the time I settled on those terms
consistently, a version had already shipped with `interface JSDoc`
having `SyntaxKind.JSDocComment`.

However, there is now a `type JSDocComment` that represents the possible
contents of the comment text (strings and various kinds of `@link`), so
it's doubly confusing that this type has a union of four kinds instead
of SyntaxKind.JSDocComment.

Although this is a public API break, I don't think it's hard to recover
from, and the JSDoc API has accessors for individual tag types, so I
suspect few people refer directly to SyntaxKind.JSDocComment.

* Add deprecate JSDocComment alias to JSDoc

For backward compatibility

* Make JSDoc an alias of JSDocComment

Improves output of JSDocParsing tests without having to make its code
smarter.

* update API baselines

Author: sandersn

src/compiler/checker.ts

@@ -1831,7 +1831,7 @@ namespace ts {
                             // - parameters are only in the scope of function body
                             // This restriction does not apply to JSDoc comment types because they are parented
                             // at a higher level than type parameters would normally be
-                            if (meaning & result.flags & SymbolFlags.Type && lastLocation.kind !== SyntaxKind.JSDocComment) {
+                            if (meaning & result.flags & SymbolFlags.Type && lastLocation.kind !== SyntaxKind.JSDoc) {
                                 useResult = result.flags & SymbolFlags.TypeParameter
                                     // type parameters are visible in parameter list, return type and type parameter list
                                     ? lastLocation === (location as FunctionLikeDeclaration).type ||
@@ -9963,7 +9963,7 @@ namespace ts {
                             node = paramSymbol.valueDeclaration!;
                         }
                         break;
-                    case SyntaxKind.JSDocComment: {
+                    case SyntaxKind.JSDoc: {
                         const outerTypeParameters = getOuterTypeParameters(node, includeThisTypes);
                         return (node as JSDoc).tags
                             ? appendTypeParameters(outerTypeParameters, flatMap((node as JSDoc).tags, t => isJSDocTemplateTag(t) ? t.typeParameters : undefined))
@@ -13660,7 +13660,7 @@ namespace ts {
         function getConditionalFlowTypeOfType(type: Type, node: Node) {
             let constraints: Type[] | undefined;
             let covariant = true;
-            while (node && !isStatement(node) && node.kind !== SyntaxKind.JSDocComment) {
+            while (node && !isStatement(node) && node.kind !== SyntaxKind.JSDoc) {
                 const parent = node.parent;
                 // only consider variance flipped by parameter locations - `keyof` types would usually be considered variance inverting, but
                 // often get used in indexed accesses where they behave sortof invariantly, but our checking is lax

src/compiler/emitter.ts

@@ -1596,7 +1596,7 @@ namespace ts {
                         return emitRestOrJSDocVariadicType(node as RestTypeNode | JSDocVariadicType);
                     case SyntaxKind.JSDocNamepathType:
                         return;
-                    case SyntaxKind.JSDocComment:
+                    case SyntaxKind.JSDoc:
                         return emitJSDoc(node as JSDoc);
                     case SyntaxKind.JSDocTypeLiteral:
                         return emitJSDocTypeLiteral(node as JSDocTypeLiteral);

src/compiler/factory/nodeFactory.ts

@@ -4740,7 +4740,7 @@ namespace ts {
 
         // @api
         function createJSDocComment(comment?: string | NodeArray<JSDocComment> | undefined, tags?: readonly JSDocTag[] | undefined) {
-            const node = createBaseNode<JSDoc>(SyntaxKind.JSDocComment);
+            const node = createBaseNode<JSDoc>(SyntaxKind.JSDoc);
             node.comment = comment;
             node.tags = asNodeArray(tags);
             return node;

src/compiler/factory/nodeTests.ts

@@ -836,7 +836,7 @@ namespace ts {
     }
 
     export function isJSDoc(node: Node): node is JSDoc {
-        return node.kind === SyntaxKind.JSDocComment;
+        return node.kind === SyntaxKind.JSDoc;
     }
 
     export function isJSDocTypeLiteral(node: Node): node is JSDocTypeLiteral {

src/compiler/parser.ts

@@ -495,7 +495,7 @@ namespace ts {
             case SyntaxKind.JSDocFunctionType:
                 return visitNodes(cbNode, cbNodes, (node as JSDocFunctionType).parameters) ||
                     visitNode(cbNode, (node as JSDocFunctionType).type);
-            case SyntaxKind.JSDocComment:
+            case SyntaxKind.JSDoc:
                 return (typeof (node as JSDoc).comment === "string" ? undefined : visitNodes(cbNode, cbNodes, (node as JSDoc).comment as NodeArray<JSDocComment> | undefined))
                     || visitNodes(cbNode, cbNodes, (node as JSDoc).tags);
             case SyntaxKind.JSDocSeeTag:

src/compiler/types.ts

@@ -378,6 +378,7 @@ namespace ts {
         JSDocFunctionType,
         JSDocVariadicType,
         JSDocNamepathType, // https://jsdoc.app/about-namepaths.html
+        /** @deprecated Use SyntaxKind.JSDoc */
         JSDocComment,
         JSDocText,
         JSDocTypeLiteral,
@@ -455,6 +456,7 @@ namespace ts {
         LastJSDocTagNode = JSDocPropertyTag,
         /* @internal */ FirstContextualKeyword = AbstractKeyword,
         /* @internal */ LastContextualKeyword = OfKeyword,
+        JSDoc = JSDocComment,
     }
 
     export type TriviaSyntaxKind =
@@ -3256,7 +3258,7 @@ namespace ts {
         ;
 
     export interface JSDoc extends Node {
-        readonly kind: SyntaxKind.JSDocComment;
+        readonly kind: SyntaxKind.JSDoc;
         readonly parent: HasJSDoc;
         readonly tags?: NodeArray<JSDocTag>;
         readonly comment?: string | NodeArray<JSDocComment>;

src/compiler/utilities.ts

@@ -4610,7 +4610,7 @@ namespace ts {
 
     /** template tags are only available when a typedef isn't already using them */
     function isNonTypeAliasTemplate(tag: JSDocTag): tag is JSDocTemplateTag {
-        return isJSDocTemplateTag(tag) && !(tag.parent.kind === SyntaxKind.JSDocComment && tag.parent.tags!.some(isJSDocTypeAlias));
+        return isJSDocTemplateTag(tag) && !(tag.parent.kind === SyntaxKind.JSDoc && tag.parent.tags!.some(isJSDocTypeAlias));
     }
 
     /**

src/compiler/utilitiesPublic.ts

@@ -926,7 +926,7 @@ namespace ts {
             return emptyArray;
         }
         if (isJSDocTypeAlias(node)) {
-            Debug.assert(node.parent.kind === SyntaxKind.JSDocComment);
+            Debug.assert(node.parent.kind === SyntaxKind.JSDoc);
             return flatMap(node.parent.tags, tag => isJSDocTemplateTag(tag) ? tag.typeParameters : undefined);
         }
         if (node.typeParameters) {
@@ -1912,7 +1912,7 @@ namespace ts {
 
     /** True if node is of a kind that may contain comment text. */
     export function isJSDocCommentContainingNode(node: Node): boolean {
-        return node.kind === SyntaxKind.JSDocComment
+        return node.kind === SyntaxKind.JSDoc
             || node.kind === SyntaxKind.JSDocNamepathType
             || node.kind === SyntaxKind.JSDocText
             || isJSDocLinkLike(node)

tests/baselines/reference/JSDocParsing/DocComments.parsesCorrectly.@@ does not start a new tag.json

@@ -1,5 +1,5 @@
 {
-    "kind": "JSDocComment",
+    "kind": "JSDoc",
     "pos": 0,
     "end": 54,
     "flags": "JSDoc",

tests/baselines/reference/JSDocParsing/DocComments.parsesCorrectly.@link tags.json

@@ -1,5 +1,5 @@
 {
-    "kind": "JSDocComment",
+    "kind": "JSDoc",
     "pos": 0,
     "end": 674,
     "flags": "JSDoc",