Add tests for parsing JSDoc comments.

Author: CyrusNajmabadi

src/compiler/parser.ts

@@ -5389,18 +5389,20 @@ module ts {
     // Parses out a JSDoc type expression.  The starting position should be right at the open
     // curly in the type expression.  Returns 'undefined' if it encounters any errors while parsing.
     /* @internal */
-    export function parseJSDocTypeExpression(content: string, start?: number, length?: number): JSDocType {
+    export function parseJSDocTypeExpression(content: string, start?: number, length?: number): JSDocTypeExpression {
         let scanner = createScanner(ScriptTarget.Latest, /*skipTrivia:*/ true, content, /*onError:*/ undefined, start, length);
 
         // Prime the first token for us to start processing.
         let token = nextToken();
         let error = false;
 
+        let result = <JSDocTypeExpression>createNode(SyntaxKind.JSDocTypeExpression);
+
         parseExpected(SyntaxKind.OpenBraceToken);
-        let type = parseJSDocType();
+        result.type = parseJSDocType();
         parseExpected(SyntaxKind.CloseBraceToken);
 
-        return error ? undefined : type;
+        return error ? undefined : finishNode(result);
 
         function nextToken(): SyntaxKind {
             return token = scanner.scan();
@@ -5738,10 +5740,12 @@ module ts {
 
         let error = false;
         let type : JSDocType;
-        let parameterTypes: JSDocType[];
+        let parameters: JSDocParameter[];
         let returnType: JSDocType;
         let typeParameterNames: string[];
 
+        let pos: number;
+
         if (length >= "/** */".length) {
             if (content.charCodeAt(start) === CharacterCodes.slash &&
                 content.charCodeAt(start + 1) === CharacterCodes.asterisk &&
@@ -5753,9 +5757,21 @@ module ts {
                 let canParseTag = true;
                 let seenAsterisk = true;
 
-                for (let i = start + 3; !error && i < end; i++) {
-                    let ch = content.charCodeAt(i);
+                for (pos = start + 3; !error && pos < end; ) {
+                    let ch = content.charCodeAt(pos);
+
+                    if (ch === CharacterCodes.at && canParseTag) {
+                        // Don't update 'pos' in this block.  that will be handled inside the 
+                        // parseTag function.
+
+                        parseTag();
+                        
+                        // Once we parse out a tag, we cannot keep parsing out tags on this line.
+                        canParseTag = false;
+                        continue;
+                    }
 
+                    pos++;
                     if (isLineBreak(ch)) {
                         // After a line break, we can parse a tag, and we haven't seen as asterisk
                         // on the next line yet.
@@ -5769,14 +5785,6 @@ module ts {
                         continue;
                     }
 
-                    if (ch === CharacterCodes.at && canParseTag) {
-                        i = parseTag(i);
-                        
-                        // Once we parse out a tag, we cannot keep parsing out tags on this line.
-                        canParseTag = false;
-                        continue;
-                    }
-
                     // Ignore the first asterisk on a line.
                     if (ch === CharacterCodes.asterisk) {
                         if (seenAsterisk) {
@@ -5799,126 +5807,125 @@ module ts {
         return error ? undefined : createJSDocComment();
 
         function createJSDocComment(): JSDocComment {
-            if (!returnType && !type && !parameterTypes && !typeParameterNames) {
+            if (!returnType && !type && !parameters && !typeParameterNames) {
                 return undefined;
             }
 
-            return { returnType, type, parameterTypes, typeParameterNames };
+            return { returnType, type, parameters, typeParameterNames };
         }
 
-        function skipWhitespace(pos: number): number {
+        function skipWhitespace(): void {
             while (pos < end && isWhiteSpace(content.charCodeAt(pos))) {
                 pos++;
             }
-
-            return pos;
         }
 
-        function parseTag(pos: number): number {
+        function parseTag(): void {
             Debug.assert(content.charCodeAt(pos) === CharacterCodes.at);
+        
+            // Skip the @ sign.
+            pos++;
 
-            // Scan forward to figure out the tag name.
-            for (var i = pos + 1; i < end; i++) {
-                if (!isIdentifierStart(content.charCodeAt(i), ScriptTarget.Latest)) {
-                    break;
-                }
-            }
-
-            let tagName = content.substring(pos + 1, i);
+            let tagName = scanIdentifier();
             switch (tagName) {
                 case "param":
-                    return handleParamTag(i);
+                    return handleParamTag();
                 case "return":
-                    return handleReturnTag(i);
+                    return handleReturnTag();
                 case "template":
-                    return handleTemplateTag(i);
+                    return handleTemplateTag();
                 case "type":
-                    return handleTypeTag(i);
+                    return handleTypeTag();
             }
-
-            return i;
         }
 
-        function handleParamTag(pos: number) {
-            let typeExpr = parseJSDocTypeExpression(content, pos, end - pos);
-            if (!typeExpr) {
+        function parseType(): JSDocType {
+            let typeExpression = parseJSDocTypeExpression(content, pos, end - pos);
+            if (!typeExpression) {
                 error = true;
-                return pos;
+                return undefined;
+            }
+
+            pos = typeExpression.end;
+            return typeExpression.type;
+        }
+
+        function handleParamTag() {
+            let type = parseType();
+            if (!type) {
+                return;
             }
 
-            parameterTypes = parameterTypes || [];
-            parameterTypes.push(typeExpr);
-            return typeExpr.end;
+            skipWhitespace();
+
+            let name = scanIdentifier();
+            parameters = parameters || [];
+            parameters.push({ name, type });
         }
 
-        function handleReturnTag(pos: number) {
+        function handleReturnTag(): void {
             if (!returnType) {
-                let typeExpr = parseJSDocTypeExpression(content, pos, end - pos);
-                if (typeExpr) {
-                    returnType = typeExpr;
-                    return typeExpr.end;
+                returnType = parseType();
+                if (returnType) {
+                    return;
                 }
             }
 
             error = true;
-            return pos;
         }
 
-        function handleTypeTag(pos: number) {
+        function handleTypeTag(): void {
             if (!type) {
-                let typeExpr = parseJSDocTypeExpression(content, pos, end - pos);
-                if (typeExpr) {
-                    type = typeExpr;
-                    return typeExpr.end;
+                type = parseType();
+                if (type) {
+                    return;
                 }
             }
 
             error = true;
-            return pos;
         }
 
-        function handleTemplateTag(pos: number): number {
+        function handleTemplateTag(): void {
             if (!typeParameterNames) {
                 typeParameterNames = [];
 
                 while (!error) {
-                    pos = skipWhitespace(pos);
-                    scanTypeParameterName();
-                    pos = skipWhitespace(pos);
+                    skipWhitespace();
+                    let name = scanIdentifier();
+                    typeParameterNames.push(name);
+
+                    skipWhitespace();
                     if (content.charCodeAt(pos) !== CharacterCodes.comma) {
-                        break;
+                        return;
                     }
-                }
 
-                if (typeParameterNames.length > 0) {
-                    return pos;
+                    pos++;
                 }
             }
 
             error = true;
-            return pos;
-
-            function scanTypeParameterName() {
-                for (var i = pos; i < end; i++) {
-                    let ch = content.charCodeAt(i);
-                    if (i === pos && isIdentifierStart(ch, ScriptTarget.Latest)) {
-                        continue;
-                    }
-                    else if (i > pos && isIdentifierPart(ch, ScriptTarget.Latest)) {
-                        continue;
-                    }
+        }
 
-                    break;
+        function scanIdentifier(): string {
+            let startPos = pos;
+            for (;pos < end; pos++) {
+                let ch = content.charCodeAt(pos);
+                if (pos === startPos && isIdentifierStart(ch, ScriptTarget.Latest)) {
+                    continue;
                 }
-
-                if (i === pos) {
-                    error = true;
-                    return;
+                else if (pos > startPos && isIdentifierPart(ch, ScriptTarget.Latest)) {
+                    continue;
                 }
 
-                typeParameterNames.push(content.substring(pos, i));
-                pos = i;
+                break;
+            }
+
+            if (startPos === pos) {
+                error = true;
+                return;
             }
+
+            return content.substring(startPos, pos); 
         }
     }
 

src/compiler/types.ts

@@ -270,6 +270,7 @@ module ts {
         SourceFile,
 
         // JSDoc nodes.
+        JSDocTypeExpression,
         // The * type.
         JSDocAllType,
         // The ? type.
@@ -1010,6 +1011,11 @@ module ts {
         hasTrailingNewLine?: boolean;
     }
 
+    // represents a top level: { type } expression in a JSDoc comment.
+    export interface JSDocTypeExpression extends Node {
+        type: JSDocType;
+    }
+
     export interface JSDocType extends Node {
         _jsDocTypeBrand: any;
     }
@@ -1069,9 +1075,14 @@ module ts {
         type?: JSDocType
     }
 
+    export interface JSDocParameter {
+        name: string;
+        type: JSDocType;
+    }
+
     export interface JSDocComment {
         type?: JSDocType;
-        parameterTypes?: JSDocType[];
+        parameters?: JSDocParameter[];
         returnType?: JSDocType;
         typeParameterNames?: string[];
     }