Microsoft/TypeScript
1
0
Fork 0
mirror of https://github.com/microsoft/TypeScript.git synced 2025-11-18 17:21:48 +00:00
Code Issues Packages Projects Releases Wiki Activity

Rename SyntaxKind.JSDocComment -> JSDoc (#44416)

Browse Source 
* 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
This commit is contained in:
Nathan Shively-Sanders
2022-03-09 09:51:29 -08:00
committed by GitHub
parent 94a7ec17e0
commit 918f0ef404
49 changed files with 58 additions and 52 deletions
Download Patch File Download Diff File Expand all files Collapse all files
src/compiler/checker.ts
+3 -3
View File
@@ -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
+1 -1
View File
@@ -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
+1 -1
View File
@@ -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
+1 -1
View File
@@ -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
+1 -1
View File
@@ -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
+3 -1
View File
@@ -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
+1 -1
View File
@@ -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
+2 -2
View File
@@ -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 -1
View File
@@ -1,5 +1,5 @@
{
"kind": "JSDocComment",
"kind": "JSDoc",
"pos": 0,
"end": 54,
"flags": "JSDoc",
tests/baselines/reference/JSDocParsing/DocComments.parsesCorrectly.@link tags.json
+1 -1
View File
@@ -1,5 +1,5 @@
{
"kind": "JSDocComment",
"kind": "JSDoc",
"pos": 0,
"end": 674,
"flags": "JSDoc",
tests/baselines/reference/JSDocParsing/DocComments.parsesCorrectly.Chained tags, no leading whitespace.json
+1 -1
View File
@@ -1,5 +1,5 @@
{
"kind": "JSDocComment",
"kind": "JSDoc",
"pos": 0,
"end": 15,
"flags": "JSDoc",
tests/baselines/reference/JSDocParsing/DocComments.parsesCorrectly.Initial email address is not a tag.json
+1 -1
View File
@@ -1,5 +1,5 @@
{
"kind": "JSDocComment",
"kind": "JSDoc",
"pos": 0,
"end": 21,
"flags": "JSDoc",
tests/baselines/reference/JSDocParsing/DocComments.parsesCorrectly.Initial star is not a tag.json
+1 -1
View File
@@ -1,5 +1,5 @@
{
"kind": "JSDocComment",
"kind": "JSDoc",
"pos": 0,
"end": 8,
"flags": "JSDoc",
tests/baselines/reference/JSDocParsing/DocComments.parsesCorrectly.Initial star space is not a tag.json
+1 -1
View File
@@ -1,5 +1,5 @@
{
"kind": "JSDocComment",
"kind": "JSDoc",
"pos": 0,
"end": 9,
"flags": "JSDoc",
tests/baselines/reference/JSDocParsing/DocComments.parsesCorrectly.Nested @param tags.json
+1 -1
View File
@@ -1,5 +1,5 @@
{
"kind": "JSDocComment",
"kind": "JSDoc",
"pos": 0,
"end": 66,
"flags": "JSDoc",
tests/baselines/reference/JSDocParsing/DocComments.parsesCorrectly.argSynonymForParamTag.json
+1 -1
View File
@@ -1,5 +1,5 @@
{
"kind": "JSDocComment",
"kind": "JSDoc",
"pos": 0,
"end": 44,
"flags": "JSDoc",
tests/baselines/reference/JSDocParsing/DocComments.parsesCorrectly.argumentSynonymForParamTag.json
+1 -1
View File
@@ -1,5 +1,5 @@
{
"kind": "JSDocComment",
"kind": "JSDoc",
"pos": 0,
"end": 49,
"flags": "JSDoc",
tests/baselines/reference/JSDocParsing/DocComments.parsesCorrectly.asteriskAfterPreamble.json
+1 -1
View File
@@ -1,5 +1,5 @@
{
"kind": "JSDocComment",
"kind": "JSDoc",
"pos": 0,
"end": 23,
"flags": "JSDoc",
tests/baselines/reference/JSDocParsing/DocComments.parsesCorrectly.authorTag.json
+1 -1
View File
@@ -1,5 +1,5 @@
{
"kind": "JSDocComment",
"kind": "JSDoc",
"pos": 0,
"end": 739,
"flags": "JSDoc",
tests/baselines/reference/JSDocParsing/DocComments.parsesCorrectly.consecutive newline tokens.json
+1 -1
View File
@@ -1,5 +1,5 @@
{
"kind": "JSDocComment",
"kind": "JSDoc",
"pos": 0,
"end": 55,
"flags": "JSDoc",
tests/baselines/reference/JSDocParsing/DocComments.parsesCorrectly.emptyComment.json
+1 -1
View File
@@ -1,5 +1,5 @@
{
"kind": "JSDocComment",
"kind": "JSDoc",
"pos": 0,
"end": 5,
"flags": "JSDoc",
tests/baselines/reference/JSDocParsing/DocComments.parsesCorrectly.leadingAsterisk.json
+1 -1
View File
@@ -1,5 +1,5 @@
{
"kind": "JSDocComment",
"kind": "JSDoc",
"pos": 0,
"end": 27,
"flags": "JSDoc",
tests/baselines/reference/JSDocParsing/DocComments.parsesCorrectly.less-than and greater-than characters.json
+1 -1
View File
@@ -1,5 +1,5 @@
{
"kind": "JSDocComment",
"kind": "JSDoc",
"pos": 0,
"end": 61,
"flags": "JSDoc",
tests/baselines/reference/JSDocParsing/DocComments.parsesCorrectly.no space before @ is not a new tag.json
+1 -1
View File
@@ -1,5 +1,5 @@
{
"kind": "JSDocComment",
"kind": "JSDoc",
"pos": 0,
"end": 91,
"flags": "JSDoc",
tests/baselines/reference/JSDocParsing/DocComments.parsesCorrectly.noLeadingAsterisk.json
+1 -1
View File
@@ -1,5 +1,5 @@
{
"kind": "JSDocComment",
"kind": "JSDoc",
"pos": 0,
"end": 27,
"flags": "JSDoc",
tests/baselines/reference/JSDocParsing/DocComments.parsesCorrectly.noReturnType.json
+1 -1
View File
@@ -1,5 +1,5 @@
{
"kind": "JSDocComment",
"kind": "JSDoc",
"pos": 0,
"end": 20,
"flags": "JSDoc",
tests/baselines/reference/JSDocParsing/DocComments.parsesCorrectly.oneParamTag.json
+1 -1
View File
@@ -1,5 +1,5 @@
{
"kind": "JSDocComment",
"kind": "JSDoc",
"pos": 0,
"end": 34,
"flags": "JSDoc",
tests/baselines/reference/JSDocParsing/DocComments.parsesCorrectly.paramTag1.json
+1 -1
View File
@@ -1,5 +1,5 @@
{
"kind": "JSDocComment",
"kind": "JSDoc",
"pos": 0,
"end": 59,
"flags": "JSDoc",
tests/baselines/reference/JSDocParsing/DocComments.parsesCorrectly.paramTagBracketedName1.json
+1 -1
View File
@@ -1,5 +1,5 @@
{
"kind": "JSDocComment",
"kind": "JSDoc",
"pos": 0,
"end": 61,
"flags": "JSDoc",
tests/baselines/reference/JSDocParsing/DocComments.parsesCorrectly.paramTagBracketedName2.json
+1 -1
View File
@@ -1,5 +1,5 @@
{
"kind": "JSDocComment",
"kind": "JSDoc",
"pos": 0,
"end": 66,
"flags": "JSDoc",
tests/baselines/reference/JSDocParsing/DocComments.parsesCorrectly.paramTagNameThenType1.json
+1 -1
View File
@@ -1,5 +1,5 @@
{
"kind": "JSDocComment",
"kind": "JSDoc",
"pos": 0,
"end": 34,
"flags": "JSDoc",
tests/baselines/reference/JSDocParsing/DocComments.parsesCorrectly.paramTagNameThenType2.json
+1 -1
View File
@@ -1,5 +1,5 @@
{
"kind": "JSDocComment",
"kind": "JSDoc",
"pos": 0,
"end": 46,
"flags": "JSDoc",
tests/baselines/reference/JSDocParsing/DocComments.parsesCorrectly.paramWithoutType.json
+1 -1
View File
@@ -1,5 +1,5 @@
{
"kind": "JSDocComment",
"kind": "JSDoc",
"pos": 0,
"end": 23,
"flags": "JSDoc",
tests/baselines/reference/JSDocParsing/DocComments.parsesCorrectly.returnTag1.json
+1 -1
View File
@@ -1,5 +1,5 @@
{
"kind": "JSDocComment",
"kind": "JSDoc",
"pos": 0,
"end": 29,
"flags": "JSDoc",
tests/baselines/reference/JSDocParsing/DocComments.parsesCorrectly.returnTag2.json
+1 -1
View File
@@ -1,5 +1,5 @@
{
"kind": "JSDocComment",
"kind": "JSDoc",
"pos": 0,
"end": 54,
"flags": "JSDoc",
tests/baselines/reference/JSDocParsing/DocComments.parsesCorrectly.returnsTag1.json
+1 -1
View File
@@ -1,5 +1,5 @@
{
"kind": "JSDocComment",
"kind": "JSDoc",
"pos": 0,
"end": 30,
"flags": "JSDoc",
tests/baselines/reference/JSDocParsing/DocComments.parsesCorrectly.templateTag.json
+1 -1
View File
@@ -1,5 +1,5 @@
{
"kind": "JSDocComment",
"kind": "JSDoc",
"pos": 0,
"end": 24,
"flags": "JSDoc",
tests/baselines/reference/JSDocParsing/DocComments.parsesCorrectly.templateTag2.json
+1 -1
View File
@@ -1,5 +1,5 @@
{
"kind": "JSDocComment",
"kind": "JSDoc",
"pos": 0,
"end": 26,
"flags": "JSDoc",
tests/baselines/reference/JSDocParsing/DocComments.parsesCorrectly.templateTag3.json
+1 -1
View File
@@ -1,5 +1,5 @@
{
"kind": "JSDocComment",
"kind": "JSDoc",
"pos": 0,
"end": 27,
"flags": "JSDoc",
tests/baselines/reference/JSDocParsing/DocComments.parsesCorrectly.templateTag4.json
+1 -1
View File
@@ -1,5 +1,5 @@
{
"kind": "JSDocComment",
"kind": "JSDoc",
"pos": 0,
"end": 27,
"flags": "JSDoc",
tests/baselines/reference/JSDocParsing/DocComments.parsesCorrectly.templateTag5.json
+1 -1
View File
@@ -1,5 +1,5 @@
{
"kind": "JSDocComment",
"kind": "JSDoc",
"pos": 0,
"end": 28,
"flags": "JSDoc",
tests/baselines/reference/JSDocParsing/DocComments.parsesCorrectly.templateTag6.json
+1 -1
View File
@@ -1,5 +1,5 @@
{
"kind": "JSDocComment",
"kind": "JSDoc",
"pos": 0,
"end": 60,
"flags": "JSDoc",
tests/baselines/reference/JSDocParsing/DocComments.parsesCorrectly.threeAsterisks.json
+1 -1
View File
@@ -1,5 +1,5 @@
{
"kind": "JSDocComment",
"kind": "JSDoc",
"pos": 0,
"end": 7,
"flags": "JSDoc",
tests/baselines/reference/JSDocParsing/DocComments.parsesCorrectly.twoParamTag2.json
+1 -1
View File
@@ -1,5 +1,5 @@
{
"kind": "JSDocComment",
"kind": "JSDoc",
"pos": 0,
"end": 60,
"flags": "JSDoc",
tests/baselines/reference/JSDocParsing/DocComments.parsesCorrectly.twoParamTagOnSameLine.json
+1 -1
View File
@@ -1,5 +1,5 @@
{
"kind": "JSDocComment",
"kind": "JSDoc",
"pos": 0,
"end": 56,
"flags": "JSDoc",
tests/baselines/reference/JSDocParsing/DocComments.parsesCorrectly.typeTag.json
+1 -1
View File
@@ -1,5 +1,5 @@
{
"kind": "JSDocComment",
"kind": "JSDoc",
"pos": 0,
"end": 27,
"flags": "JSDoc",
tests/baselines/reference/JSDocParsing/DocComments.parsesCorrectly.typedefTagWithChildrenTags.json
+1 -1
View File
@@ -1,5 +1,5 @@
{
"kind": "JSDocComment",
"kind": "JSDoc",
"pos": 0,
"end": 102,
"flags": "JSDoc",
tests/baselines/reference/api/tsserverlibrary.d.ts
Vendored
+3 -1
View File
@@ -424,6 +424,7 @@ declare namespace ts {
JSDocFunctionType = 316,
JSDocVariadicType = 317,
JSDocNamepathType = 318,
/** @deprecated Use SyntaxKind.JSDoc */
JSDocComment = 319,
JSDocText = 320,
JSDocTypeLiteral = 321,
@@ -491,6 +492,7 @@ declare namespace ts {
LastJSDocNode = 346,
FirstJSDocTagNode = 326,
LastJSDocTagNode = 346,
JSDoc = 319
}
export type TriviaSyntaxKind = SyntaxKind.SingleLineCommentTrivia | SyntaxKind.MultiLineCommentTrivia | SyntaxKind.NewLineTrivia | SyntaxKind.WhitespaceTrivia | SyntaxKind.ShebangTrivia | SyntaxKind.ConflictMarkerTrivia;
export type LiteralSyntaxKind = SyntaxKind.NumericLiteral | SyntaxKind.BigIntLiteral | SyntaxKind.StringLiteral | SyntaxKind.JsxText | SyntaxKind.JsxTextAllWhiteSpaces | SyntaxKind.RegularExpressionLiteral | SyntaxKind.NoSubstitutionTemplateLiteral;
@@ -1820,7 +1822,7 @@ declare namespace ts {
}
export type JSDocTypeReferencingNode = JSDocVariadicType | JSDocOptionalType | JSDocNullableType | JSDocNonNullableType;
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>;
tests/baselines/reference/api/typescript.d.ts
Vendored
+3 -1
View File
@@ -424,6 +424,7 @@ declare namespace ts {
JSDocFunctionType = 316,
JSDocVariadicType = 317,
JSDocNamepathType = 318,
/** @deprecated Use SyntaxKind.JSDoc */
JSDocComment = 319,
JSDocText = 320,
JSDocTypeLiteral = 321,
@@ -491,6 +492,7 @@ declare namespace ts {
LastJSDocNode = 346,
FirstJSDocTagNode = 326,
LastJSDocTagNode = 346,
JSDoc = 319
}
export type TriviaSyntaxKind = SyntaxKind.SingleLineCommentTrivia | SyntaxKind.MultiLineCommentTrivia | SyntaxKind.NewLineTrivia | SyntaxKind.WhitespaceTrivia | SyntaxKind.ShebangTrivia | SyntaxKind.ConflictMarkerTrivia;
export type LiteralSyntaxKind = SyntaxKind.NumericLiteral | SyntaxKind.BigIntLiteral | SyntaxKind.StringLiteral | SyntaxKind.JsxText | SyntaxKind.JsxTextAllWhiteSpaces | SyntaxKind.RegularExpressionLiteral | SyntaxKind.NoSubstitutionTemplateLiteral;
@@ -1820,7 +1822,7 @@ declare namespace ts {
}
export type JSDocTypeReferencingNode = JSDocVariadicType | JSDocOptionalType | JSDocNullableType | JSDocNonNullableType;
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>;