diff --git a/src/compiler/binder.ts b/src/compiler/binder.ts index a617c9063da50..5fdfc7f02be42 100644 --- a/src/compiler/binder.ts +++ b/src/compiler/binder.ts @@ -263,6 +263,18 @@ namespace ts { let functionType = node.parent; let index = indexOf(functionType.parameters, node); return "p" + index; + case SyntaxKind.JSDocTypedefTag: + const parentNode = node.parent && node.parent.parent; + let nameFromParentNode: string; + if (parentNode && parentNode.kind === SyntaxKind.VariableStatement) { + if ((parentNode).declarationList.declarations.length > 0) { + const nameIdentifier = (parentNode).declarationList.declarations[0].name; + if (nameIdentifier.kind === SyntaxKind.Identifier) { + nameFromParentNode = (nameIdentifier).text; + } + } + } + return nameFromParentNode; } } @@ -402,6 +414,7 @@ namespace ts { // these saved values. const saveContainer = container; const savedBlockScopeContainer = blockScopeContainer; + // Depending on what kind of node this is, we may have to adjust the current container // and block-container. If the current node is a container, then it is automatically // considered the current block-container as well. Also, for containers that we know @@ -491,8 +504,13 @@ namespace ts { } function bindChildren(node: Node): void { - if (node.flags & NodeFlags.JavaScriptFile && node.jsDocComment) { - bind(node.jsDocComment); + // Binding of JsDocComment should be done before the current block scope container changes. + // because the scope of JsDocComment should not be affected by whether the current node is a + // container or not. + if (isInJavaScriptFile(node) && node.jsDocComments) { + for (const jsDocComment of node.jsDocComments) { + bind(jsDocComment); + } } if (checkUnreachable(node)) { forEachChild(node, bind); @@ -1090,6 +1108,7 @@ namespace ts { case SyntaxKind.EnumDeclaration: case SyntaxKind.ObjectLiteralExpression: case SyntaxKind.TypeLiteral: + case SyntaxKind.JSDocTypeLiteral: case SyntaxKind.JSDocRecordType: return ContainerFlags.IsContainer; @@ -1190,6 +1209,7 @@ namespace ts { case SyntaxKind.ObjectLiteralExpression: case SyntaxKind.InterfaceDeclaration: case SyntaxKind.JSDocRecordType: + case SyntaxKind.JSDocTypeLiteral: // Interface/Object-types always have their children added to the 'members' of // their container. They are only accessible through an instance of their // container, and are never in scope otherwise (even inside the body of the @@ -1218,7 +1238,7 @@ namespace ts { // their container in the tree. To accomplish this, we simply add their declared // symbol to the 'locals' of the container. These symbols can then be found as // the type checker walks up the containers, checking them for matching names. - return declareSymbol(container.locals, undefined, node, symbolFlags, symbolExcludes); + return declareSymbol(container.locals, /*parent*/ undefined, node, symbolFlags, symbolExcludes); } } @@ -1679,6 +1699,8 @@ namespace ts { case SyntaxKind.PropertySignature: case SyntaxKind.JSDocRecordMember: return bindPropertyOrMethodOrAccessor(node, SymbolFlags.Property | ((node).questionToken ? SymbolFlags.Optional : SymbolFlags.None), SymbolFlags.PropertyExcludes); + case SyntaxKind.JSDocPropertyTag: + return bindJSDocProperty(node); case SyntaxKind.PropertyAssignment: case SyntaxKind.ShorthandPropertyAssignment: return bindPropertyOrMethodOrAccessor(node, SymbolFlags.Property, SymbolFlags.PropertyExcludes); @@ -1714,6 +1736,7 @@ namespace ts { case SyntaxKind.JSDocFunctionType: return bindFunctionOrConstructorType(node); case SyntaxKind.TypeLiteral: + case SyntaxKind.JSDocTypeLiteral: case SyntaxKind.JSDocRecordType: return bindAnonymousDeclaration(node, SymbolFlags.TypeLiteral, "__type"); case SyntaxKind.ObjectLiteralExpression: @@ -1736,6 +1759,7 @@ namespace ts { return bindClassLikeDeclaration(node); case SyntaxKind.InterfaceDeclaration: return bindBlockScopedDeclaration(node, SymbolFlags.Interface, SymbolFlags.InterfaceExcludes); + case SyntaxKind.JSDocTypedefTag: case SyntaxKind.TypeAliasDeclaration: return bindBlockScopedDeclaration(node, SymbolFlags.TypeAlias, SymbolFlags.TypeAliasExcludes); case SyntaxKind.EnumDeclaration: @@ -2077,6 +2101,10 @@ namespace ts { : declareSymbolAndAddToSymbolTable(node, symbolFlags, symbolExcludes); } + function bindJSDocProperty(node: JSDocPropertyTag) { + return declareSymbolAndAddToSymbolTable(node, SymbolFlags.Property, SymbolFlags.PropertyExcludes); + } + // reachability checks function shouldReportErrorOnModuleDeclaration(node: ModuleDeclaration): boolean { diff --git a/src/compiler/checker.ts b/src/compiler/checker.ts index b67248fcb294d..06ef246340252 100644 --- a/src/compiler/checker.ts +++ b/src/compiler/checker.ts @@ -3581,8 +3581,22 @@ namespace ts { if (!pushTypeResolution(symbol, TypeSystemPropertyName.DeclaredType)) { return unknownType; } - const declaration = getDeclarationOfKind(symbol, SyntaxKind.TypeAliasDeclaration); - let type = getTypeFromTypeNode(declaration.type); + + let type: Type; + let declaration: JSDocTypedefTag | TypeAliasDeclaration = getDeclarationOfKind(symbol, SyntaxKind.JSDocTypedefTag); + if (declaration) { + if (declaration.jsDocTypeLiteral) { + type = getTypeFromTypeNode(declaration.jsDocTypeLiteral); + } + else { + type = getTypeFromTypeNode(declaration.typeExpression.type); + } + } + else { + declaration = getDeclarationOfKind(symbol, SyntaxKind.TypeAliasDeclaration); + type = getTypeFromTypeNode(declaration.type); + } + if (popTypeResolution()) { links.typeParameters = getLocalTypeParametersOfClassOrInterfaceOrTypeAlias(symbol); if (links.typeParameters) { @@ -5253,6 +5267,7 @@ namespace ts { case SyntaxKind.FunctionType: case SyntaxKind.ConstructorType: case SyntaxKind.TypeLiteral: + case SyntaxKind.JSDocTypeLiteral: case SyntaxKind.JSDocFunctionType: case SyntaxKind.JSDocRecordType: return getTypeFromTypeLiteralOrFunctionOrConstructorTypeNode(node); @@ -16728,7 +16743,7 @@ namespace ts { node = node.parent; } - return node.parent && node.parent.kind === SyntaxKind.TypeReference; + return node.parent && (node.parent.kind === SyntaxKind.TypeReference || node.parent.kind === SyntaxKind.JSDocTypeReference) ; } function isHeritageClauseElementIdentifier(entityName: Node): boolean { @@ -16864,7 +16879,7 @@ namespace ts { } } else if (isTypeReferenceIdentifier(entityName)) { - let meaning = entityName.parent.kind === SyntaxKind.TypeReference ? SymbolFlags.Type : SymbolFlags.Namespace; + let meaning = (entityName.parent.kind === SyntaxKind.TypeReference || entityName.parent.kind === SyntaxKind.JSDocTypeReference) ? SymbolFlags.Type : SymbolFlags.Namespace; // Include aliases in the meaning, this ensures that we do not follow aliases to where they point and instead // return the alias symbol. meaning |= SymbolFlags.Alias; diff --git a/src/compiler/diagnosticMessages.json b/src/compiler/diagnosticMessages.json index af8dd8ceb6971..034bd27b1472a 100644 --- a/src/compiler/diagnosticMessages.json +++ b/src/compiler/diagnosticMessages.json @@ -819,6 +819,10 @@ "category": "Error", "code": 1252 }, + "'{0}' tag cannot be used independently as a top level JSDoc tag.": { + "category": "Error", + "code": 1253 + }, "'with' statements are not allowed in an async function block.": { "category": "Error", "code": 1300 diff --git a/src/compiler/parser.ts b/src/compiler/parser.ts index 2672efb647c9a..6f042627c6ba4 100644 --- a/src/compiler/parser.ts +++ b/src/compiler/parser.ts @@ -401,6 +401,15 @@ namespace ts { return visitNode(cbNode, (node).typeExpression); case SyntaxKind.JSDocTemplateTag: return visitNodes(cbNodes, (node).typeParameters); + case SyntaxKind.JSDocTypedefTag: + return visitNode(cbNode, (node).typeExpression) || + visitNode(cbNode, (node).name) || + visitNode(cbNode, (node).jsDocTypeLiteral); + case SyntaxKind.JSDocTypeLiteral: + return visitNodes(cbNodes, (node).jsDocPropertyTags); + case SyntaxKind.JSDocPropertyTag: + return visitNode(cbNode, (node).typeExpression) || + visitNode(cbNode, (node).name); } } @@ -628,9 +637,14 @@ namespace ts { if (comments) { for (const comment of comments) { const jsDocComment = JSDocParser.parseJSDocComment(node, comment.pos, comment.end - comment.pos); - if (jsDocComment) { - node.jsDocComment = jsDocComment; + if (!jsDocComment) { + continue; } + + if (!node.jsDocComments) { + node.jsDocComments = []; + } + node.jsDocComments.push(jsDocComment); } } } @@ -658,6 +672,13 @@ namespace ts { const saveParent = parent; parent = n; forEachChild(n, visitNode); + if (n.jsDocComments) { + for (const jsDocComment of n.jsDocComments) { + jsDocComment.parent = n; + parent = jsDocComment; + forEachChild(jsDocComment, visitNode); + } + } parent = saveParent; } } @@ -2704,7 +2725,7 @@ namespace ts { // 1) async[no LineTerminator here]AsyncArrowBindingIdentifier[?Yield][no LineTerminator here]=>AsyncConciseBody[?In] // 2) CoverCallExpressionAndAsyncArrowHead[?Yield, ?Await][no LineTerminator here]=>AsyncConciseBody[?In] // Production (1) of AsyncArrowFunctionExpression is parsed in "tryParseAsyncSimpleArrowFunctionExpression". - // And production (2) is parsed in "tryParseParenthesizedArrowFunctionExpression". + // And production (2) is parsed in "tryParseParenthesizedArrowFunctionExpression". // // If we do successfully parse arrow-function, we must *not* recurse for productions 1, 2 or 3. An ArrowFunction is // not a LeftHandSideExpression, nor does it start a ConditionalExpression. So we are done @@ -3396,8 +3417,8 @@ namespace ts { if (sourceFile.languageVariant !== LanguageVariant.JSX) { return false; } - // We are in JSX context and the token is part of JSXElement. - // Fall through + // We are in JSX context and the token is part of JSXElement. + // Fall through default: return true; } @@ -4099,9 +4120,9 @@ namespace ts { const isAsync = !!(node.flags & NodeFlags.Async); node.name = isGenerator && isAsync ? doInYieldAndAwaitContext(parseOptionalIdentifier) : - isGenerator ? doInYieldContext(parseOptionalIdentifier) : - isAsync ? doInAwaitContext(parseOptionalIdentifier) : - parseOptionalIdentifier(); + isGenerator ? doInYieldContext(parseOptionalIdentifier) : + isAsync ? doInAwaitContext(parseOptionalIdentifier) : + parseOptionalIdentifier(); fillSignature(SyntaxKind.ColonToken, /*yieldContext*/ isGenerator, /*awaitContext*/ isAsync, /*requireCompleteParameterList*/ false, node); node.body = parseFunctionBlock(/*allowYield*/ isGenerator, /*allowAwait*/ isAsync, /*ignoreMissingOpenBrace*/ false); @@ -5891,7 +5912,7 @@ namespace ts { } function checkForEmptyTypeArgumentList(typeArguments: NodeArray) { - if (parseDiagnostics.length === 0 && typeArguments && typeArguments.length === 0) { + if (parseDiagnostics.length === 0 && typeArguments && typeArguments.length === 0) { const start = typeArguments.pos - "<".length; const end = skipTrivia(sourceText, typeArguments.end) + ">".length; return parseErrorAtPosition(start, end - start, Diagnostics.Type_argument_list_cannot_be_empty); @@ -6052,7 +6073,6 @@ namespace ts { Debug.assert(end <= content.length); let tags: NodeArray; - let result: JSDocComment; // Check for /** (JSDoc opening part) @@ -6159,6 +6179,8 @@ namespace ts { return handleTemplateTag(atToken, tagName); case "type": return handleTypeTag(atToken, tagName); + case "typedef": + return handleTypedefTag(atToken, tagName); } } @@ -6266,6 +6288,122 @@ namespace ts { return finishNode(result); } + function handlePropertyTag(atToken: Node, tagName: Identifier): JSDocPropertyTag { + const typeExpression = tryParseTypeExpression(); + skipWhitespace(); + const name = parseJSDocIdentifierName(); + if (!name) { + parseErrorAtPosition(scanner.getStartPos(), /*length*/ 0, Diagnostics.Identifier_expected); + return undefined; + } + + const result = createNode(SyntaxKind.JSDocPropertyTag, atToken.pos); + result.atToken = atToken; + result.tagName = tagName; + result.name = name; + result.typeExpression = typeExpression; + return finishNode(result); + } + + function handleTypedefTag(atToken: Node, tagName: Identifier): JSDocTypedefTag { + const typeExpression = tryParseTypeExpression(); + skipWhitespace(); + + const typedefTag = createNode(SyntaxKind.JSDocTypedefTag, atToken.pos); + typedefTag.atToken = atToken; + typedefTag.tagName = tagName; + typedefTag.name = parseJSDocIdentifierName(); + typedefTag.typeExpression = typeExpression; + + if (typeExpression) { + if (typeExpression.type.kind === SyntaxKind.JSDocTypeReference) { + const jsDocTypeReference = typeExpression.type; + if (jsDocTypeReference.name.kind === SyntaxKind.Identifier) { + const name = jsDocTypeReference.name; + if (name.text === "Object") { + typedefTag.jsDocTypeLiteral = scanChildTags(); + } + } + } + if (!typedefTag.jsDocTypeLiteral) { + typedefTag.jsDocTypeLiteral = typeExpression.type; + } + } + else { + typedefTag.jsDocTypeLiteral = scanChildTags(); + } + + return finishNode(typedefTag); + + function scanChildTags(): JSDocTypeLiteral { + const jsDocTypeLiteral = createNode(SyntaxKind.JSDocTypeLiteral, scanner.getStartPos()); + let resumePos = scanner.getStartPos(); + let canParseTag = true; + let seenAsterisk = false; + let parentTagTerminated = false; + + while (token !== SyntaxKind.EndOfFileToken && !parentTagTerminated) { + nextJSDocToken(); + switch (token) { + case SyntaxKind.AtToken: + if (canParseTag) { + parentTagTerminated = !tryParseChildTag(jsDocTypeLiteral); + } + seenAsterisk = false; + break; + case SyntaxKind.NewLineTrivia: + resumePos = scanner.getStartPos() - 1; + canParseTag = true; + seenAsterisk = false; + break; + case SyntaxKind.AsteriskToken: + if (seenAsterisk) { + canParseTag = false; + } + seenAsterisk = true; + break; + case SyntaxKind.Identifier: + canParseTag = false; + case SyntaxKind.EndOfFileToken: + break; + } + } + scanner.setTextPos(resumePos); + return finishNode(jsDocTypeLiteral); + } + } + + function tryParseChildTag(parentTag: JSDocTypeLiteral): boolean { + Debug.assert(token === SyntaxKind.AtToken); + const atToken = createNode(SyntaxKind.AtToken, scanner.getStartPos()); + atToken.end = scanner.getTextPos(); + nextJSDocToken(); + + const tagName = parseJSDocIdentifierName(); + if (!tagName) { + return false; + } + + switch (tagName.text) { + case "type": + if (parentTag.jsDocTypeTag) { + // already has a @type tag, terminate the parent tag now. + return false; + } + parentTag.jsDocTypeTag = handleTypeTag(atToken, tagName); + return true; + case "prop": + case "property": + if (!parentTag.jsDocPropertyTags) { + parentTag.jsDocPropertyTags = >[]; + } + const propertyTag = handlePropertyTag(atToken, tagName); + parentTag.jsDocPropertyTags.push(propertyTag); + return true; + } + return false; + } + function handleTemplateTag(atToken: Node, tagName: Identifier): JSDocTemplateTag { if (forEach(tags, t => t.kind === SyntaxKind.JSDocTemplateTag)) { parseErrorAtPosition(tagName.pos, scanner.getTokenPos() - tagName.pos, Diagnostics._0_tag_already_specified, tagName.text); @@ -6435,10 +6573,6 @@ namespace ts { node._children = undefined; } - if (node.jsDocComment) { - node.jsDocComment = undefined; - } - node.pos += delta; node.end += delta; @@ -6447,6 +6581,11 @@ namespace ts { } forEachChild(node, visitNode, visitArray); + if (node.jsDocComments) { + for (const jsDocComment of node.jsDocComments) { + forEachChild(jsDocComment, visitNode, visitArray); + } + } checkNodePositions(node, aggressiveChecks); } diff --git a/src/compiler/scanner.ts b/src/compiler/scanner.ts index 1a2748b38b15f..82359eacc3eac 100644 --- a/src/compiler/scanner.ts +++ b/src/compiler/scanner.ts @@ -434,7 +434,7 @@ namespace ts { } /* @internal */ - export function skipTrivia(text: string, pos: number, stopAfterLineBreak?: boolean): number { + export function skipTrivia(text: string, pos: number, stopAfterLineBreak?: boolean, stopAtComments = false): number { // Using ! with a greater than test is a fast way of testing the following conditions: // pos === undefined || pos === null || isNaN(pos) || pos < 0; if (!(pos >= 0)) { @@ -462,6 +462,9 @@ namespace ts { pos++; continue; case CharacterCodes.slash: + if (stopAtComments) { + break; + } if (text.charCodeAt(pos + 1) === CharacterCodes.slash) { pos += 2; while (pos < text.length) { diff --git a/src/compiler/types.ts b/src/compiler/types.ts index 4e55956fa7c20..c7e14a1003108 100644 --- a/src/compiler/types.ts +++ b/src/compiler/types.ts @@ -343,6 +343,9 @@ namespace ts { JSDocReturnTag, JSDocTypeTag, JSDocTemplateTag, + JSDocTypedefTag, + JSDocPropertyTag, + JSDocTypeLiteral, // Synthesized list SyntaxList, @@ -372,6 +375,10 @@ namespace ts { FirstBinaryOperator = LessThanToken, LastBinaryOperator = CaretEqualsToken, FirstNode = QualifiedName, + FirstJSDocNode = JSDocTypeExpression, + LastJSDocNode = JSDocTypeLiteral, + FirstJSDocTagNode = JSDocComment, + LastJSDocTagNode = JSDocTypeLiteral } export const enum NodeFlags { @@ -449,7 +456,7 @@ namespace ts { modifiers?: ModifiersArray; // Array of modifiers /* @internal */ id?: number; // Unique id (used to look up NodeLinks) parent?: Node; // Parent node (initialized by binding - /* @internal */ jsDocComment?: JSDocComment; // JSDoc for the node, if it has any. Only for .js files. + /* @internal */ jsDocComments?: JSDocComment[]; // JSDoc for the node, if it has any. Only for .js files. /* @internal */ symbol?: Symbol; // Symbol declared by node (initialized by binding) /* @internal */ locals?: SymbolTable; // Locals associated with node (initialized by binding) /* @internal */ nextContainer?: Node; // Next container in declaration order (initialized by binding) @@ -613,6 +620,7 @@ namespace ts { // SyntaxKind.PropertyAssignment // SyntaxKind.ShorthandPropertyAssignment // SyntaxKind.EnumMember + // SyntaxKind.JSDocPropertyTag export interface VariableLikeDeclaration extends Declaration { propertyName?: PropertyName; dotDotDotToken?: Node; @@ -1511,6 +1519,25 @@ namespace ts { typeExpression: JSDocTypeExpression; } + // @kind(SyntaxKind.JSDocTypedefTag) + export interface JSDocTypedefTag extends JSDocTag, Declaration { + name?: Identifier; + typeExpression?: JSDocTypeExpression; + jsDocTypeLiteral?: JSDocTypeLiteral; + } + + // @kind(SyntaxKind.JSDocPropertyTag) + export interface JSDocPropertyTag extends JSDocTag, TypeElement { + name: Identifier; + typeExpression: JSDocTypeExpression; + } + + // @kind(SyntaxKind.JSDocTypeLiteral) + export interface JSDocTypeLiteral extends JSDocType { + jsDocPropertyTags?: NodeArray; + jsDocTypeTag?: JSDocTypeTag; + } + // @kind(SyntaxKind.JSDocParameterTag) export interface JSDocParameterTag extends JSDocTag { preParameterName?: Identifier; @@ -2883,4 +2910,9 @@ namespace ts { /* @internal */ reattachFileDiagnostics(newFile: SourceFile): void; } + + // SyntaxKind.SyntaxList + export interface SyntaxList extends Node { + _children: Node[]; + } } diff --git a/src/compiler/utilities.ts b/src/compiler/utilities.ts index 500fa722dda3d..74ea3459b2359 100644 --- a/src/compiler/utilities.ts +++ b/src/compiler/utilities.ts @@ -287,16 +287,36 @@ namespace ts { return !nodeIsMissing(node); } - export function getTokenPosOfNode(node: Node, sourceFile?: SourceFile): number { + export function getTokenPosOfNode(node: Node, sourceFile?: SourceFile, includeJsDocComment?: boolean): number { // With nodes that have no width (i.e. 'Missing' nodes), we actually *don't* // want to skip trivia because this will launch us forward to the next token. if (nodeIsMissing(node)) { return node.pos; } + if (isJSDocNode(node)) { + return skipTrivia((sourceFile || getSourceFileOfNode(node)).text, node.pos, /*stopAfterLineBreak*/ false, /*stopAtComments*/ true); + } + + if (includeJsDocComment && node.jsDocComments && node.jsDocComments.length > 0) { + return getTokenPosOfNode(node.jsDocComments[0]); + } + + // For a syntax list, it is possible that one of its children has JSDocComment nodes, while + // the syntax list itself considers them as normal trivia. Therefore if we simply skip + // trivia for the list, we may have skipped the JSDocComment as well. So we should process its + // first child to determine the actual position of its first token. + if (node.kind === SyntaxKind.SyntaxList && (node)._children.length > 0) { + return getTokenPosOfNode((node)._children[0], sourceFile, includeJsDocComment); + } + return skipTrivia((sourceFile || getSourceFileOfNode(node)).text, node.pos); } + export function isJSDocNode(node: Node) { + return node.kind >= SyntaxKind.FirstJSDocNode && node.kind <= SyntaxKind.LastJSDocNode; + } + export function getNonDecoratorTokenPosOfNode(node: Node, sourceFile?: SourceFile): number { if (nodeIsMissing(node) || !node.decorators) { return getTokenPosOfNode(node, sourceFile); @@ -1336,21 +1356,23 @@ namespace ts { return undefined; } - const jsDocComment = getJSDocComment(node, checkParentVariableStatement); - if (!jsDocComment) { + const jsDocComments = getJSDocComments(node, checkParentVariableStatement); + if (!jsDocComments) { return undefined; } - for (const tag of jsDocComment.tags) { - if (tag.kind === kind) { - return tag; + for (const jsDocComment of jsDocComments) { + for (const tag of jsDocComment.tags) { + if (tag.kind === kind) { + return tag; + } } } } - function getJSDocComment(node: Node, checkParentVariableStatement: boolean): JSDocComment { - if (node.jsDocComment) { - return node.jsDocComment; + function getJSDocComments(node: Node, checkParentVariableStatement: boolean): JSDocComment[] { + if (node.jsDocComments) { + return node.jsDocComments; } // Try to recognize this pattern when node is initializer of variable declaration and JSDoc comments are on containing variable statement. // /** @@ -1366,7 +1388,7 @@ namespace ts { const variableStatementNode = isInitializerOfVariableDeclarationInStatement ? node.parent.parent.parent : undefined; if (variableStatementNode) { - return variableStatementNode.jsDocComment; + return variableStatementNode.jsDocComments; } // Also recognize when the node is the RHS of an assignment expression @@ -1377,12 +1399,12 @@ namespace ts { (parent as BinaryExpression).operatorToken.kind === SyntaxKind.EqualsToken && parent.parent.kind === SyntaxKind.ExpressionStatement; if (isSourceOfAssignmentExpressionStatement) { - return parent.parent.jsDocComment; + return parent.parent.jsDocComments; } const isPropertyAssignmentExpression = parent && parent.kind === SyntaxKind.PropertyAssignment; if (isPropertyAssignmentExpression) { - return parent.jsDocComment; + return parent.jsDocComments; } } @@ -1407,14 +1429,16 @@ namespace ts { // annotation. const parameterName = (parameter.name).text; - const jsDocComment = getJSDocComment(parameter.parent, /*checkParentVariableStatement*/ true); - if (jsDocComment) { - for (const tag of jsDocComment.tags) { - if (tag.kind === SyntaxKind.JSDocParameterTag) { - const parameterTag = tag; - const name = parameterTag.preParameterName || parameterTag.postParameterName; - if (name.text === parameterName) { - return parameterTag; + const jsDocComments = getJSDocComments(parameter.parent, /*checkParentVariableStatement*/ true); + if (jsDocComments) { + for (const jsDocComment of jsDocComments) { + for (const tag of jsDocComment.tags) { + if (tag.kind === SyntaxKind.JSDocParameterTag) { + const parameterTag = tag; + const name = parameterTag.preParameterName || parameterTag.postParameterName; + if (name.text === parameterName) { + return parameterTag; + } } } } @@ -1539,6 +1563,7 @@ namespace ts { case SyntaxKind.TypeAliasDeclaration: case SyntaxKind.TypeParameter: case SyntaxKind.VariableDeclaration: + case SyntaxKind.JSDocTypedefTag: return true; } return false; diff --git a/src/harness/harness.ts b/src/harness/harness.ts index d6959c2a54fdd..5fe5b84ac9148 100644 --- a/src/harness/harness.ts +++ b/src/harness/harness.ts @@ -1,7 +1,7 @@ // // Copyright (c) Microsoft Corporation. All rights reserved. -// +// // Licensed under the Apache License, Version 2.0 (the "License"); // you may not use this file except in compliance with the License. // You may obtain a copy of the License at @@ -221,6 +221,19 @@ namespace Utils { return k; } + // For some markers in SyntaxKind, we should print its original syntax name instead of + // the marker name in tests. + if (k === (ts).SyntaxKind.FirstJSDocNode || + k === (ts).SyntaxKind.LastJSDocNode || + k === (ts).SyntaxKind.FirstJSDocTagNode || + k === (ts).SyntaxKind.LastJSDocTagNode) { + for (const kindName in (ts).SyntaxKind) { + if ((ts).SyntaxKind[kindName] === k) { + return kindName; + } + } + } + return (ts).SyntaxKind[k]; } @@ -350,7 +363,7 @@ namespace Utils { assert.equal(node1.end, node2.end, "node1.end !== node2.end"); assert.equal(node1.kind, node2.kind, "node1.kind !== node2.kind"); - // call this on both nodes to ensure all propagated flags have been set (and thus can be + // call this on both nodes to ensure all propagated flags have been set (and thus can be // compared). assert.equal(ts.containsParseError(node1), ts.containsParseError(node2)); assert.equal(node1.flags, node2.flags, "node1.flags !== node2.flags"); @@ -751,7 +764,7 @@ namespace Harness { (emittedFile: string, emittedLine: number, emittedColumn: number, sourceFile: string, sourceLine: number, sourceColumn: number, sourceName: string): void; } - // Settings + // Settings export let userSpecifiedRoot = ""; export let lightMode = false; @@ -790,7 +803,7 @@ namespace Harness { fileName: string, sourceText: string, languageVersion: ts.ScriptTarget) { - // We'll only assert invariants outside of light mode. + // We'll only assert invariants outside of light mode. const shouldAssertInvariants = !Harness.lightMode; // Only set the parent nodes if we're asserting invariants. We don't need them otherwise. @@ -935,7 +948,7 @@ namespace Harness { libFiles?: string; } - // Additional options not already in ts.optionDeclarations + // Additional options not already in ts.optionDeclarations const harnessOptionDeclarations: ts.CommandLineOption[] = [ { name: "allowNonTsExtensions", type: "boolean" }, { name: "useCaseSensitiveFileNames", type: "boolean" }, @@ -1187,7 +1200,7 @@ namespace Harness { errLines.forEach(e => outputLines.push(e)); // do not count errors from lib.d.ts here, they are computed separately as numLibraryDiagnostics - // if lib.d.ts is explicitly included in input files and there are some errors in it (i.e. because of duplicate identifiers) + // if lib.d.ts is explicitly included in input files and there are some errors in it (i.e. because of duplicate identifiers) // then they will be added twice thus triggering 'total errors' assertion with condition // 'totalErrorsReportedInNonLibraryFiles + numLibraryDiagnostics + numTest262HarnessDiagnostics, diagnostics.length @@ -1497,7 +1510,7 @@ namespace Harness { }; testUnitData.push(newTestFile2); - // unit tests always list files explicitly + // unit tests always list files explicitly const parseConfigHost: ts.ParseConfigHost = { readDirectory: (name) => [] }; diff --git a/src/services/navigationBar.ts b/src/services/navigationBar.ts index 57726a45cb023..92cf64eac947d 100644 --- a/src/services/navigationBar.ts +++ b/src/services/navigationBar.ts @@ -652,6 +652,12 @@ namespace ts.NavigationBar { topItem.childItems.push(newItem); } + if (node.jsDocComments && node.jsDocComments.length > 0) { + for (const jsDocComment of node.jsDocComments) { + visitNode(jsDocComment); + } + } + // Add a level if traversing into a container if (newItem && (isFunctionLike(node) || isClassLike(node))) { const lastTop = topItem; @@ -731,6 +737,27 @@ namespace ts.NavigationBar { } const declName = declarationNameToString(decl.name); return getNavBarItem(declName, ScriptElementKind.constElement, [getNodeSpan(node)]); + case SyntaxKind.JSDocTypedefTag: + if ((node).name) { + return getNavBarItem( + (node).name.text, + ScriptElementKind.typeElement, + [getNodeSpan(node)]); + } + else { + const parentNode = node.parent && node.parent.parent; + if (parentNode && parentNode.kind === SyntaxKind.VariableStatement) { + if ((parentNode).declarationList.declarations.length > 0) { + const nameIdentifier = (parentNode).declarationList.declarations[0].name; + if (nameIdentifier.kind === SyntaxKind.Identifier) { + return getNavBarItem( + (nameIdentifier).text, + ScriptElementKind.typeElement, + [getNodeSpan(node)]); + } + } + } + } default: return undefined; } @@ -801,7 +828,7 @@ namespace ts.NavigationBar { } function getNodeSpan(node: Node) { - return node.kind === SyntaxKind.SourceFile + return node.kind === SyntaxKind.SourceFile ? createTextSpanFromBounds(node.getFullStart(), node.getEnd()) : createTextSpanFromBounds(node.getStart(), node.getEnd()); } diff --git a/src/services/services.ts b/src/services/services.ts index 35fb0887b3b59..90740b257c6b5 100644 --- a/src/services/services.ts +++ b/src/services/services.ts @@ -20,7 +20,7 @@ namespace ts { getChildCount(sourceFile?: SourceFile): number; getChildAt(index: number, sourceFile?: SourceFile): Node; getChildren(sourceFile?: SourceFile): Node[]; - getStart(sourceFile?: SourceFile): number; + getStart(sourceFile?: SourceFile, includeJsDocComment?: boolean): number; getFullStart(): number; getEnd(): number; getWidth(sourceFile?: SourceFile): number; @@ -172,6 +172,9 @@ namespace ts { "static", "throws", "type", + "typedef", + "property", + "prop", "version" ]; let jsDocCompletionEntries: CompletionEntry[]; @@ -189,6 +192,7 @@ namespace ts { public end: number; public flags: NodeFlags; public parent: Node; + public jsDocComments: JSDocComment[]; private _children: Node[]; constructor(kind: SyntaxKind, pos: number, end: number) { @@ -203,8 +207,8 @@ namespace ts { return getSourceFileOfNode(this); } - public getStart(sourceFile?: SourceFile): number { - return getTokenPosOfNode(this, sourceFile); + public getStart(sourceFile?: SourceFile, includeJsDocComment?: boolean): number { + return getTokenPosOfNode(this, sourceFile, includeJsDocComment); } public getFullStart(): number { @@ -235,12 +239,14 @@ namespace ts { return (sourceFile || this.getSourceFile()).text.substring(this.getStart(), this.getEnd()); } - private addSyntheticNodes(nodes: Node[], pos: number, end: number): number { + private addSyntheticNodes(nodes: Node[], pos: number, end: number, useJSDocScanner?: boolean): number { scanner.setTextPos(pos); while (pos < end) { - const token = scanner.scan(); + const token = useJSDocScanner ? scanner.scanJSDocToken() : scanner.scan(); const textPos = scanner.getTextPos(); - nodes.push(createNode(token, pos, textPos, 0, this)); + if (textPos <= end) { + nodes.push(createNode(token, pos, textPos, 0, this)); + } pos = textPos; } return pos; @@ -270,20 +276,27 @@ namespace ts { scanner.setText((sourceFile || this.getSourceFile()).text); children = []; let pos = this.pos; + const useJSDocScanner = this.kind >= SyntaxKind.FirstJSDocTagNode && this.kind <= SyntaxKind.LastJSDocTagNode; const processNode = (node: Node) => { if (pos < node.pos) { - pos = this.addSyntheticNodes(children, pos, node.pos); + pos = this.addSyntheticNodes(children, pos, node.pos, useJSDocScanner); } children.push(node); pos = node.end; }; const processNodes = (nodes: NodeArray) => { if (pos < nodes.pos) { - pos = this.addSyntheticNodes(children, pos, nodes.pos); + pos = this.addSyntheticNodes(children, pos, nodes.pos, useJSDocScanner); } children.push(this.createSyntaxList(>nodes)); pos = nodes.end; }; + // jsDocComments need to be the first children + if (this.jsDocComments) { + for (const jsDocComment of this.jsDocComments) { + processNode(jsDocComment); + } + } forEachChild(this, processNode, processNodes); if (pos < this.end) { this.addSyntheticNodes(children, pos, this.end); @@ -5637,7 +5650,7 @@ namespace ts { const sourceFile = getValidSourceFile(fileName); - const node = getTouchingPropertyName(sourceFile, position); + const node = getTouchingPropertyName(sourceFile, position, /*includeJsDocComment*/ true); if (node === sourceFile) { return undefined; } @@ -5999,7 +6012,8 @@ namespace ts { const sourceFile = container.getSourceFile(); const tripleSlashDirectivePrefixRegex = /^\/\/\/\s*= start and (position < end or (position === end && token is keyword or identifier)) */ - export function getTouchingWord(sourceFile: SourceFile, position: number): Node { - return getTouchingToken(sourceFile, position, n => isWord(n.kind)); + export function getTouchingWord(sourceFile: SourceFile, position: number, includeJsDocComment = false): Node { + return getTouchingToken(sourceFile, position, n => isWord(n.kind), includeJsDocComment); } /* Gets the token whose text has range [start, end) and position >= start * and (position < end or (position === end && token is keyword or identifier or numeric/string literal)) */ - export function getTouchingPropertyName(sourceFile: SourceFile, position: number): Node { - return getTouchingToken(sourceFile, position, n => isPropertyName(n.kind)); + export function getTouchingPropertyName(sourceFile: SourceFile, position: number, includeJsDocComment = false): Node { + return getTouchingToken(sourceFile, position, n => isPropertyName(n.kind), includeJsDocComment); } /** Returns the token if position is in [start, end) or if position === end and includeItemAtEndPosition(token) === true */ - export function getTouchingToken(sourceFile: SourceFile, position: number, includeItemAtEndPosition?: (n: Node) => boolean): Node { - return getTokenAtPositionWorker(sourceFile, position, /*allowPositionInLeadingTrivia*/ false, includeItemAtEndPosition); + export function getTouchingToken(sourceFile: SourceFile, position: number, includeItemAtEndPosition?: (n: Node) => boolean, includeJsDocComment = false): Node { + return getTokenAtPositionWorker(sourceFile, position, /*allowPositionInLeadingTrivia*/ false, includeItemAtEndPosition, includeJsDocComment); } /** Returns a token if position is in [start-of-leading-trivia, end) */ - export function getTokenAtPosition(sourceFile: SourceFile, position: number): Node { - return getTokenAtPositionWorker(sourceFile, position, /*allowPositionInLeadingTrivia*/ true, /*includeItemAtEndPosition*/ undefined); + export function getTokenAtPosition(sourceFile: SourceFile, position: number, includeJsDocComment = false): Node { + return getTokenAtPositionWorker(sourceFile, position, /*allowPositionInLeadingTrivia*/ true, /*includeItemAtEndPosition*/ undefined, includeJsDocComment); } /** Get the token whose text contains the position */ - function getTokenAtPositionWorker(sourceFile: SourceFile, position: number, allowPositionInLeadingTrivia: boolean, includeItemAtEndPosition: (n: Node) => boolean): Node { + function getTokenAtPositionWorker(sourceFile: SourceFile, position: number, allowPositionInLeadingTrivia: boolean, includeItemAtEndPosition: (n: Node) => boolean, includeJsDocComment = false): Node { let current: Node = sourceFile; outer: while (true) { if (isToken(current)) { @@ -264,13 +264,34 @@ namespace ts { return current; } + if (includeJsDocComment) { + const jsDocChildren = ts.filter(current.getChildren(), isJSDocNode); + for (const jsDocChild of jsDocChildren) { + const start = allowPositionInLeadingTrivia ? jsDocChild.getFullStart() : jsDocChild.getStart(sourceFile, includeJsDocComment); + if (start <= position) { + const end = jsDocChild.getEnd(); + if (position < end || (position === end && jsDocChild.kind === SyntaxKind.EndOfFileToken)) { + current = jsDocChild; + continue outer; + } + else if (includeItemAtEndPosition && end === position) { + const previousToken = findPrecedingToken(position, sourceFile, jsDocChild); + if (previousToken && includeItemAtEndPosition(previousToken)) { + return previousToken; + } + } + } + } + } + // find the child that contains 'position' for (let i = 0, n = current.getChildCount(sourceFile); i < n; i++) { const child = current.getChildAt(i); - if (position < child.getFullStart() || position > child.getEnd()) { + // all jsDocComment nodes were already visited + if (isJSDocNode(child)) { continue; } - const start = allowPositionInLeadingTrivia ? child.getFullStart() : child.getStart(sourceFile); + const start = allowPositionInLeadingTrivia ? child.getFullStart() : child.getStart(sourceFile, includeJsDocComment); if (start <= position) { const end = child.getEnd(); if (position < end || (position === end && child.kind === SyntaxKind.EndOfFileToken)) { @@ -285,6 +306,7 @@ namespace ts { } } } + return current; } } @@ -423,6 +445,10 @@ namespace ts { return false; } + if (token.kind === SyntaxKind.JsxText) { + return true; + } + //
Hello |
if (token.kind === SyntaxKind.LessThanToken && token.parent.kind === SyntaxKind.JsxText) { return true; @@ -433,7 +459,7 @@ namespace ts { return true; } - //
{ + //
{ // | // } < /div> if (token && token.kind === SyntaxKind.CloseBraceToken && token.parent.kind === SyntaxKind.JsxExpression) { @@ -518,11 +544,12 @@ namespace ts { } if (node) { - const jsDocComment = node.jsDocComment; - if (jsDocComment) { - for (const tag of jsDocComment.tags) { - if (tag.pos <= position && position <= tag.end) { - return tag; + if (node.jsDocComments) { + for (const jsDocComment of node.jsDocComments) { + for (const tag of jsDocComment.tags) { + if (tag.pos <= position && position <= tag.end) { + return tag; + } } } } @@ -646,7 +673,7 @@ namespace ts { // [a, b, c] of // [x, [a, b, c] ] = someExpression - // or + // or // {x, a: {a, b, c} } = someExpression if (isArrayLiteralOrObjectLiteralDestructuringPattern(node.parent.kind === SyntaxKind.PropertyAssignment ? node.parent.parent : node.parent)) { return true; diff --git a/tests/cases/fourslash/server/jsdocTypedefTag.ts b/tests/cases/fourslash/server/jsdocTypedefTag.ts new file mode 100644 index 0000000000000..e645b518020bb --- /dev/null +++ b/tests/cases/fourslash/server/jsdocTypedefTag.ts @@ -0,0 +1,64 @@ +/// + +// @allowNonTsExtensions: true +// @Filename: jsdocCompletion_typedef.js + +//// /** @typedef {(string | number)} NumberLike */ +//// +//// /** +//// * @typedef Animal +//// * @type {Object} +//// * @property {string} animalName +//// * @property {number} animalAge +//// */ +//// +//// /** +//// * @typedef {Object} Person +//// * @property {string} personName +//// * @property {number} personAge +//// */ +//// +//// /** +//// * @typedef {Object} +//// * @property {string} catName +//// * @property {number} catAge +//// */ +//// var Cat; +//// +//// /** @typedef {{ dogName: string, dogAge: number }} */ +//// var Dog; +//// +//// /** @type {NumberLike} */ +//// var numberLike; numberLike./*numberLike*/ +//// +//// /** @type {Person} */ +//// var p;p./*person*/ +//// +//// /** @type {Animal} */ +//// var a;a./*animal*/ +//// +//// /** @type {Cat} */ +//// var c;c./*cat*/ +//// +//// /** @type {Dog} */ +//// var d;d./*dog*/ + +goTo.marker('numberLike'); +verify.memberListContains('charAt'); +verify.memberListContains('toExponential'); + +goTo.marker('person'); +verify.memberListContains('personName'); +verify.memberListContains('personAge'); + +goTo.marker('animal'); +verify.memberListContains('animalName'); +verify.memberListContains('animalAge'); + +goTo.marker('dog'); +verify.memberListContains('dogName'); +verify.memberListContains('dogAge'); + +goTo.marker('cat'); +verify.memberListContains('catName'); +verify.memberListContains('catAge'); \ No newline at end of file diff --git a/tests/cases/fourslash/server/jsdocTypedefTagGoToDefinition.ts b/tests/cases/fourslash/server/jsdocTypedefTagGoToDefinition.ts new file mode 100644 index 0000000000000..4db14611938b7 --- /dev/null +++ b/tests/cases/fourslash/server/jsdocTypedefTagGoToDefinition.ts @@ -0,0 +1,29 @@ +/// + +// @allowNonTsExtensions: true +// @Filename: jsdocCompletion_typedef.js + +//// /** +//// * @typedef {Object} Person +//// * /*1*/@property {string} personName +//// * @property {number} personAge +//// */ +//// +//// /** +//// * @typedef {{ /*2*/animalName: string, animalAge: number }} Animal +//// */ +//// +//// /** @type {Person} */ +//// var person; person.personName/*3*/ +//// +//// /** @type {Animal} */ +//// var animal; animal.animalName/*4*/ + +goTo.file('jsdocCompletion_typedef.js'); +goTo.marker('3'); +goTo.definition(); +verify.caretAtMarker('1'); + +goTo.marker('4'); +goTo.definition(); +verify.caretAtMarker('2'); diff --git a/tests/cases/fourslash/server/jsdocTypedefTagNavigateTo.ts b/tests/cases/fourslash/server/jsdocTypedefTagNavigateTo.ts new file mode 100644 index 0000000000000..77cd75aa44c77 --- /dev/null +++ b/tests/cases/fourslash/server/jsdocTypedefTagNavigateTo.ts @@ -0,0 +1,30 @@ +/// + +// @allowNonTsExtensions: true +// @Filename: jsDocTypedef_form2.js +//// +//// /** @typedef {(string | number)} NumberLike */ +//// /** @typedef {(string | number | string[])} */ +//// var NumberLike2; +//// +//// /** @type {/*1*/NumberLike} */ +//// var numberLike; + +verify.navigationBar([ + { + "text": "NumberLike", + "kind": "type" + }, + { + "text": "NumberLike2", + "kind": "type" + }, + { + "text": "NumberLike2", + "kind": "var" + }, + { + "text": "numberLike", + "kind": "var" + } +]); \ No newline at end of file diff --git a/tests/cases/fourslash/server/jsdocTypedefTagRename01.ts b/tests/cases/fourslash/server/jsdocTypedefTagRename01.ts new file mode 100644 index 0000000000000..776d0180b0689 --- /dev/null +++ b/tests/cases/fourslash/server/jsdocTypedefTagRename01.ts @@ -0,0 +1,20 @@ +/// + +// @allowNonTsExtensions: true +// @Filename: jsDocTypedef_form1.js +//// +//// /** @typedef {(string | number)} */ +//// var /*1*/[|NumberLike|]; +//// +//// /*2*/[|NumberLike|] = 10; +//// +//// /** @type {/*3*/[|NumberLike|]} */ +//// var numberLike; + +goTo.file('jsDocTypedef_form1.js') +goTo.marker('1'); +verify.renameLocations(/*findInStrings*/ false, /*findInComments*/ true); +goTo.marker('2'); +verify.renameLocations(/*findInStrings*/ false, /*findInComments*/ true); +goTo.marker('3'); +verify.renameLocations(/*findInStrings*/ false, /*findInComments*/ true); \ No newline at end of file diff --git a/tests/cases/fourslash/server/jsdocTypedefTagRename02.ts b/tests/cases/fourslash/server/jsdocTypedefTagRename02.ts new file mode 100644 index 0000000000000..7f1d422d971d9 --- /dev/null +++ b/tests/cases/fourslash/server/jsdocTypedefTagRename02.ts @@ -0,0 +1,15 @@ +/// + +// @allowNonTsExtensions: true +// @Filename: jsDocTypedef_form2.js +//// +//// /** @typedef {(string | number)} /*1*/[|NumberLike|] */ +//// +//// /** @type {/*2*/[|NumberLike|]} */ +//// var numberLike; + +goTo.file('jsDocTypedef_form2.js') +goTo.marker('1'); +verify.renameLocations(/*findInStrings*/ false, /*findInComments*/ true); +goTo.marker('2'); +verify.renameLocations(/*findInStrings*/ false, /*findInComments*/ true); \ No newline at end of file diff --git a/tests/cases/fourslash/server/jsdocTypedefTagRename03.ts b/tests/cases/fourslash/server/jsdocTypedefTagRename03.ts new file mode 100644 index 0000000000000..c1b389458069d --- /dev/null +++ b/tests/cases/fourslash/server/jsdocTypedefTagRename03.ts @@ -0,0 +1,20 @@ +/// + +// @allowNonTsExtensions: true +// @Filename: jsDocTypedef_form3.js +//// +//// /** +//// * @typedef /*1*/[|Person|] +//// * @type {Object} +//// * @property {number} age +//// * @property {string} name +//// */ +//// +//// /** @type {/*2*/[|Person|]} */ +//// var person; + +goTo.file('jsDocTypedef_form3.js') +goTo.marker('1'); +verify.renameLocations(/*findInStrings*/ false, /*findInComments*/ true); +goTo.marker('2'); +verify.renameLocations(/*findInStrings*/ false, /*findInComments*/ true); \ No newline at end of file diff --git a/tests/cases/fourslash/server/jsdocTypedefTagRename04.ts b/tests/cases/fourslash/server/jsdocTypedefTagRename04.ts new file mode 100644 index 0000000000000..b7bf220512a5d --- /dev/null +++ b/tests/cases/fourslash/server/jsdocTypedefTagRename04.ts @@ -0,0 +1,24 @@ +/// + +// @allowNonTsExtensions: true +// @Filename: jsDocTypedef_form2.js +//// +//// function test1() { +//// /** @typedef {(string | number)} NumberLike */ +//// +//// /** @type {/*1*/NumberLike} */ +//// var numberLike; +//// } +//// function test2() { +//// /** @typedef {(string | number)} NumberLike2 */ +//// +//// /** @type {NumberLike2} */ +//// var n/*2*/umberLike2; +//// } + +goTo.marker('2'); +verify.quickInfoExists(); +goTo.marker('1'); +edit.insert('111'); +goTo.marker('2'); +verify.quickInfoExists(); \ No newline at end of file diff --git a/tests/cases/unittests/jsDocParsing.ts b/tests/cases/unittests/jsDocParsing.ts index 22f679c4ad546..fb75b4d494071 100644 --- a/tests/cases/unittests/jsDocParsing.ts +++ b/tests/cases/unittests/jsDocParsing.ts @@ -1004,7 +1004,8 @@ namespace ts { if (result !== expected) { // Turn on a human-readable diff if (typeof require !== "undefined") { - require("chai").config.showDiff = true; + const chai = require("chai"); + chai.config.showDiff = true; chai.expect(JSON.parse(result)).equal(JSON.parse(expected)); } else { @@ -2218,4 +2219,4 @@ namespace ts { }); }); }); -} +} \ No newline at end of file