Parsing support for jsDocComments.

This commit is contained in:
Cyrus Najmabadi 2015-05-28 10:14:18 -07:00
parent 118d87ce18
commit 9aab98419b
13 changed files with 3326 additions and 72 deletions

View file

@ -123,6 +123,7 @@ var harnessSources = [
return path.join(harnessDirectory, f);
}).concat([
"incrementalParser.ts",
"jsDocParsing.ts",
"services/colorization.ts",
"services/documentRegistry.ts",
"services/preProcessFile.ts",

View file

@ -312,8 +312,11 @@ module ts {
Debug.assert(start >= 0, "start must be non-negative, is " + start);
Debug.assert(length >= 0, "length must be non-negative, is " + length);
Debug.assert(start <= file.text.length, `start must be within the bounds of the file. ${ start } > ${ file.text.length }`);
Debug.assert(end <= file.text.length, `end must be the bounds of the file. ${ end } > ${ file.text.length }`);
if (file) {
Debug.assert(start <= file.text.length, `start must be within the bounds of the file. ${ start } > ${ file.text.length }`);
Debug.assert(end <= file.text.length, `end must be the bounds of the file. ${ end } > ${ file.text.length }`);
}
let text = getLocaleSpecificMessage(message.key);

View file

@ -174,6 +174,7 @@ module ts {
Type_expected_0_is_a_reserved_word_in_strict_mode: { code: 1215, category: DiagnosticCategory.Error, key: "Type expected. '{0}' is a reserved word in strict mode" },
Type_expected_0_is_a_reserved_word_in_strict_mode_Class_definitions_are_automatically_in_strict_mode: { code: 1216, category: DiagnosticCategory.Error, key: "Type expected. '{0}' is a reserved word in strict mode. Class definitions are automatically in strict mode." },
Export_assignment_is_not_supported_when_module_flag_is_system: { code: 1218, category: DiagnosticCategory.Error, key: "Export assignment is not supported when '--module' flag is 'system'." },
_0_tag_already_specified: { code: 1219, category: DiagnosticCategory.Error, key: "'{0}' tag already specified." },
Duplicate_identifier_0: { code: 2300, category: DiagnosticCategory.Error, key: "Duplicate identifier '{0}'." },
Initializer_of_instance_member_variable_0_cannot_reference_identifier_1_declared_in_the_constructor: { code: 2301, category: DiagnosticCategory.Error, key: "Initializer of instance member variable '{0}' cannot reference identifier '{1}' declared in the constructor." },
Static_members_cannot_reference_class_type_parameters: { code: 2302, category: DiagnosticCategory.Error, key: "Static members cannot reference class type parameters." },
@ -535,7 +536,6 @@ module ts {
types_can_only_be_used_in_a_ts_file: { code: 8010, category: DiagnosticCategory.Error, key: "'types' can only be used in a .ts file." },
type_arguments_can_only_be_used_in_a_ts_file: { code: 8011, category: DiagnosticCategory.Error, key: "'type arguments' can only be used in a .ts file." },
parameter_modifiers_can_only_be_used_in_a_ts_file: { code: 8012, category: DiagnosticCategory.Error, key: "'parameter modifiers' can only be used in a .ts file." },
can_only_be_used_in_a_ts_file: { code: 8013, category: DiagnosticCategory.Error, key: "'?' can only be used in a .ts file." },
property_declarations_can_only_be_used_in_a_ts_file: { code: 8014, category: DiagnosticCategory.Error, key: "'property declarations' can only be used in a .ts file." },
enum_declarations_can_only_be_used_in_a_ts_file: { code: 8015, category: DiagnosticCategory.Error, key: "'enum declarations' can only be used in a .ts file." },
type_assertion_expressions_can_only_be_used_in_a_ts_file: { code: 8016, category: DiagnosticCategory.Error, key: "'type assertion expressions' can only be used in a .ts file." },

View file

@ -683,7 +683,10 @@
"category": "Error",
"code": 1218
},
"'{0}' tag already specified.": {
"category": "Error",
"code": 1219
},
"Duplicate identifier '{0}'.": {
"category": "Error",
"code": 2300
@ -2132,10 +2135,6 @@
"category": "Error",
"code": 8012
},
"'?' can only be used in a .ts file.": {
"category": "Error",
"code": 8013
},
"'property declarations' can only be used in a .ts file.": {
"category": "Error",
"code": 8014

File diff suppressed because it is too large Load diff

View file

@ -598,12 +598,26 @@ module ts {
ch > CharacterCodes.maxAsciiCharacter && isUnicodeIdentifierPart(ch, languageVersion);
}
/** Creates a scanner over a (possibly unspecified) range of a piece of text. */
export function createScanner(languageVersion: ScriptTarget, skipTrivia: boolean, text?: string, onError?: ErrorCallback, start?: number, length?: number): Scanner {
let pos: number; // Current position (end position of text of current token)
let end: number; // end of text
let startPos: number; // Start position of whitespace before current token
let tokenPos: number; // Start position of text of current token
/* @internal */
// Creates a scanner over a (possibly unspecified) range of a piece of text.
export function createScanner(languageVersion: ScriptTarget,
skipTrivia: boolean,
text?: string,
onError?: ErrorCallback,
start?: number,
length?: number): Scanner {
// Current position (end position of text of current token)
let pos: number;
// end of text
let end: number;
// Start position of whitespace before current token
let startPos: number;
// Start position of text of current token
let tokenPos: number;
let token: SyntaxKind;
let tokenValue: string;
let precedingLineBreak: boolean;

View file

@ -270,6 +270,32 @@ module ts {
// Top-level nodes
SourceFile,
// JSDoc nodes.
JSDocTypeExpression,
// The * type.
JSDocAllType,
// The ? type.
JSDocUnknownType,
JSDocArrayType,
JSDocUnionType,
JSDocTupleType,
JSDocNullableType,
JSDocNonNullableType,
JSDocRecordType,
JSDocRecordMember,
JSDocTypeReference,
JSDocOptionalType,
JSDocFunctionType,
JSDocVariadicType,
JSDocConstructorType,
JSDocThisType,
JSDocComment,
JSDocTag,
JSDocParameterTag,
JSDocReturnTag,
JSDocTypeTag,
JSDocTemplateTag,
// Synthesized list
SyntaxList,
// Enum value count
@ -324,6 +350,8 @@ module ts {
/* @internal */
export const enum ParserContextFlags {
None = 0,
// Set if this node was parsed in strict mode. Used for grammar error checks, as well as
// checking if the node can be reused in incremental settings.
StrictMode = 1 << 0,
@ -345,6 +373,10 @@ module ts {
// error.
ThisNodeHasError = 1 << 5,
// This node was parsed in a JavaScript file and can be processed differently. For example
// its type can be specified usign a JSDoc comment.
JavaScriptFile = 1 << 6,
// Context flags set directly by the parser.
ParserGeneratedFlags = StrictMode | DisallowIn | Yield | GeneratorParameter | Decorator | ThisNodeHasError,
@ -352,10 +384,10 @@ module ts {
// Used during incremental parsing to determine if this node or any of its children had an
// error. Computed only once and then cached.
ThisNodeOrAnySubNodesHasError = 1 << 6,
ThisNodeOrAnySubNodesHasError = 1 << 7,
// Used to know if we've computed data from children and cached it in this node.
HasAggregatedChildData = 1 << 7
HasAggregatedChildData = 1 << 8
}
/* @internal */
@ -371,14 +403,15 @@ module ts {
// Specific context the parser was in when this node was created. Normally undefined.
// Only set when the parser was in some interesting context (like async/yield).
/* @internal */ parserContextFlags?: ParserContextFlags;
decorators?: NodeArray<Decorator>; // Array of decorators (in document order)
modifiers?: ModifiersArray; // Array of modifiers
/* @internal */ id?: number; // Unique id (used to look up NodeLinks)
parent?: Node; // Parent node (initialized by binding)
/* @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)
/* @internal */ localSymbol?: Symbol; // Local symbol declared by node (initialized by binding only for exported nodes)
decorators?: NodeArray<Decorator>; // Array of decorators (in document order)
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 */ 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)
/* @internal */ localSymbol?: Symbol; // Local symbol declared by node (initialized by binding only for exported nodes)
}
export interface NodeArray<T> extends Array<T>, TextRange {
@ -992,6 +1025,106 @@ module ts {
kind: SyntaxKind;
}
// represents a top level: { type } expression in a JSDoc comment.
export interface JSDocTypeExpression extends Node {
type: JSDocType;
}
export interface JSDocType extends TypeNode {
_jsDocTypeBrand: any;
}
export interface JSDocAllType extends JSDocType {
_JSDocAllTypeBrand: any;
}
export interface JSDocUnknownType extends JSDocType {
_JSDocUnknownTypeBrand: any;
}
export interface JSDocArrayType extends JSDocType {
elementType: JSDocType;
}
export interface JSDocUnionType extends JSDocType {
types: NodeArray<JSDocType>;
}
export interface JSDocTupleType extends JSDocType {
types: NodeArray<JSDocType>;
}
export interface JSDocNonNullableType extends JSDocType {
type: JSDocType;
}
export interface JSDocNullableType extends JSDocType {
type: JSDocType;
}
export interface JSDocRecordType extends JSDocType, TypeLiteralNode {
members: NodeArray<JSDocRecordMember>;
}
export interface JSDocTypeReference extends JSDocType {
name: EntityName;
typeArguments: NodeArray<JSDocType>
}
export interface JSDocOptionalType extends JSDocType {
type: JSDocType;
}
export interface JSDocFunctionType extends JSDocType, SignatureDeclaration {
parameters: NodeArray<ParameterDeclaration>;
type: JSDocType;
}
export interface JSDocVariadicType extends JSDocType {
type: JSDocType;
}
export interface JSDocConstructorType extends JSDocType {
type: JSDocType;
}
export interface JSDocThisType extends JSDocType {
type: JSDocType;
}
export interface JSDocRecordMember extends PropertyDeclaration {
name: Identifier | LiteralExpression,
type?: JSDocType
}
export interface JSDocComment extends Node {
tags: NodeArray<JSDocTag>;
}
export interface JSDocTag extends Node {
atToken: Node;
tagName: Identifier;
}
export interface JSDocTemplateTag extends JSDocTag {
typeParameters: NodeArray<TypeParameterDeclaration>;
}
export interface JSDocReturnTag extends JSDocTag {
typeExpression: JSDocTypeExpression;
}
export interface JSDocTypeTag extends JSDocTag {
typeExpression: JSDocTypeExpression;
}
export interface JSDocParameterTag extends JSDocTag {
preParameterName?: Identifier;
typeExpression?: JSDocTypeExpression;
postParameterName?: Identifier;
isBracketed: boolean;
}
// Source files are declarations when they are external modules.
export interface SourceFile extends Declaration {
statements: NodeArray<ModuleElement>;

View file

@ -468,6 +468,12 @@ module ts {
return false;
}
export function isClassLike(node: Node): boolean {
if (node) {
return node.kind === SyntaxKind.ClassDeclaration || node.kind === SyntaxKind.ClassExpression;
}
}
export function isFunctionLike(node: Node): boolean {
if (node) {
switch (node.kind) {
@ -830,7 +836,7 @@ module ts {
}
export function hasDotDotDotToken(node: Node) {
return node && node.kind === SyntaxKind.Parameter && (<ParameterDeclaration>node).dotDotDotToken !== undefined;
return node && node.kind === SyntaxKind.Parameter && (<ParameterDeclaration>node).dotDotDotToken !== undefined;
}
export function hasQuestionToken(node: Node) {
@ -856,6 +862,78 @@ module ts {
return s.parameters.length > 0 && lastOrUndefined(s.parameters).dotDotDotToken !== undefined;
}
export function isJSDocConstructSignature(node: Node) {
return node.kind === SyntaxKind.JSDocFunctionType &&
(<JSDocFunctionType>node).parameters.length > 0 &&
(<JSDocFunctionType>node).parameters[0].type.kind === SyntaxKind.JSDocConstructorType;
}
function getJSDocTag(node: Node, kind: SyntaxKind): JSDocTag {
if (node && node.jsDocComment) {
for (let tag of node.jsDocComment.tags) {
if (tag.kind === kind) {
return tag;
}
}
}
}
export function getJSDocTypeTag(node: Node): JSDocTypeTag {
return <JSDocTypeTag>getJSDocTag(node, SyntaxKind.JSDocTypeTag);
}
export function getJSDocReturnTag(node: Node): JSDocReturnTag {
return <JSDocReturnTag>getJSDocTag(node, SyntaxKind.JSDocReturnTag);
}
export function getJSDocTemplateTag(node: Node): JSDocTemplateTag {
return <JSDocTemplateTag>getJSDocTag(node, SyntaxKind.JSDocTemplateTag);
}
export function getCorrespondingJSDocParameterTag(parameter: ParameterDeclaration): JSDocParameterTag {
if (parameter.name && parameter.name.kind === SyntaxKind.Identifier) {
// If it's a parameter, see if the parent has a jsdoc comment with an @param
// annotation.
let parameterName = (<Identifier>parameter.name).text;
let docComment = parameter.parent.jsDocComment;
if (docComment) {
return <JSDocParameterTag>forEach(docComment.tags, t => {
if (t.kind === SyntaxKind.JSDocParameterTag) {
let parameterTag = <JSDocParameterTag>t;
let name = parameterTag.preParameterName || parameterTag.postParameterName;
if (name.text === parameterName) {
return t;
}
}
});
}
}
}
export function hasRestParameter(s: SignatureDeclaration): boolean {
return isRestParameter(lastOrUndefined(s.parameters));
}
export function isRestParameter(node: ParameterDeclaration) {
if (node) {
if (node.parserContextFlags & ParserContextFlags.JavaScriptFile) {
if (node.type && node.type.kind === SyntaxKind.JSDocVariadicType) {
return true;
}
let paramTag = getCorrespondingJSDocParameterTag(node);
if (paramTag && paramTag.typeExpression) {
return paramTag.typeExpression.type.kind === SyntaxKind.JSDocVariadicType;
}
}
return node.dotDotDotToken !== undefined;
}
return false;
}
export function isLiteralKind(kind: SyntaxKind): boolean {
return SyntaxKind.FirstLiteralToken <= kind && kind <= SyntaxKind.LastLiteralToken;
}
@ -1707,6 +1785,10 @@ module ts {
return symbol && symbol.valueDeclaration && (symbol.valueDeclaration.flags & NodeFlags.Default) ? symbol.valueDeclaration.localSymbol : undefined;
}
export function isJavaScript(fileName: string) {
return fileExtensionIs(fileName, ".js");
}
/**
* Replace each instance of non-ascii characters by one, two, three, or four escape sequences
* representing the UTF-8 encoding of the character, and return the expanded char code list.
@ -2000,4 +2082,14 @@ module ts {
return createTextChangeRange(createTextSpanFromBounds(oldStartN, oldEndN), /*newLength:*/ newEndN - oldStartN);
}
export function getTypeParameterOwner(d: Declaration): Declaration {
if (d && d.kind === SyntaxKind.TypeParameter) {
for (let current: Node = d; current; current = current.parent) {
if (isFunctionLike(current) || isClassLike(current) || current.kind === SyntaxKind.InterfaceDeclaration) {
return <Declaration>current;
}
}
}
}
}

View file

@ -193,12 +193,16 @@ module Utils {
};
}
export function sourceFileToJSON(file: ts.SourceFile): string {
export function sourceFileToJSON(file: ts.Node): string {
return JSON.stringify(file,(k, v) => {
return isNodeOrArray(v) ? serializeNode(v) : v;
}, " ");
function getKindName(k: number): string {
function getKindName(k: number | string): string {
if (typeof k === "string") {
return k;
}
return (<any>ts).SyntaxKind[k]
}
@ -231,7 +235,9 @@ module Utils {
function serializeNode(n: ts.Node): any {
var o: any = { kind: getKindName(n.kind) };
o.containsParseError = ts.containsParseError(n);
if (ts.containsParseError(n)) {
o.containsParseError = true;
}
ts.forEach(Object.getOwnPropertyNames(n), propertyName => {
switch (propertyName) {
@ -249,6 +255,10 @@ module Utils {
// Blacklist of items we never put in the baseline file.
break;
case "originalKeywordKind":
o[propertyName] = getKindName((<any>n)[propertyName]);
break;
case "flags":
// Print out flags with their enum names.
o[propertyName] = getNodeFlagName(n.flags);

View file

@ -2698,7 +2698,7 @@ module ts {
return true;
}
if (parameter.questionToken) {
diagnostics.push(createDiagnosticForNode(parameter.questionToken, Diagnostics.can_only_be_used_in_a_ts_file));
diagnostics.push(createDiagnosticForNode(parameter.questionToken, Diagnostics._0_can_only_be_used_in_a_ts_file, '?'));
return true;
}
if (parameter.type) {

View file

@ -652,8 +652,4 @@ module ts {
typechecker.getSymbolDisplayBuilder().buildSignatureDisplay(signature, writer, enclosingDeclaration, flags);
});
}
export function isJavaScript(fileName: string) {
return fileExtensionIs(fileName, ".js");
}
}

View file

@ -10,6 +10,6 @@ verify.getSemanticDiagnostics(`[
"start": 12,
"length": 1,
"category": "error",
"code": 8013
"code": 8009
}
]`);

File diff suppressed because it is too large Load diff