Loosen restrictions on jsdoc completion locations

uniqueiniquity · uniqueiniquity · commit 612616a1058d · 2017-11-03T09:53:56.000-07:00
diff --git a/src/services/jsDoc.ts b/src/services/jsDoc.ts
@@ -1,5 +1,6 @@
 /* @internal */
 namespace ts.JsDoc {
+    const singleLineTemplate = { newText: "/** */", caretOffset: 3 };
     const jsDocTagNames = [
         "augments",
         "author",
@@ -170,15 +171,9 @@ namespace ts.JsDoc {
     /**
      * Checks if position points to a valid position to add JSDoc comments, and if so,
      * returns the appropriate template. Otherwise returns an empty string.
-     * Valid positions are
-     *      - outside of comments, statements, and expressions, and
-     *      - preceding a:
-     *          - function/constructor/method declaration
-     *          - class declarations
-     *          - variable statements
-     *          - namespace declarations
-     *          - interface declarations
-     *          - method signatures
+     * Invalid positions are
+     *      - within comments, strings (including template literals and regex), and JSXText
+     *      - within a token
      *
      * Hosts should ideally check that:
      * - The line is all whitespace up to 'position' before performing the insertion.
@@ -204,17 +199,23 @@ namespace ts.JsDoc {
 
         const commentOwnerInfo = getCommentOwnerInfo(tokenAtPos);
         if (!commentOwnerInfo) {
-            return undefined;
+            // if climbing the tree did not find a declaration with parameters, complete to a single line comment
+            return singleLineTemplate;
         }
         const { commentOwner, parameters } = commentOwnerInfo;
-        if (commentOwner.getStart() < position) {
+
+        if (commentOwner.kind === SyntaxKind.JsxText) {
             return undefined;
         }
 
-        if (!parameters || parameters.length === 0) {
-            // if there are no parameters, just complete to a single line JSDoc comment
-            const singleLineResult = "/** */";
-            return { newText: singleLineResult, caretOffset: 3 };
+        if (commentOwner.getStart() < position) {
+            // if climbing the tree found a declaration with parameters but the request was made inside it, complete to a single line comment
+            return singleLineTemplate;
+        }
+
+        if (parameters.length === 0) {
+            // if there are no parameters, complete to a single line comment
+            return singleLineTemplate;
         }
 
         const posLineAndChar = sourceFile.getLineAndCharacterOfPosition(position);
@@ -258,7 +259,7 @@ namespace ts.JsDoc {
 
     interface CommentOwnerInfo {
         readonly commentOwner: Node;
-        readonly parameters?: ReadonlyArray<ParameterDeclaration>;
+        readonly parameters: ReadonlyArray<ParameterDeclaration>;
     }
     function getCommentOwnerInfo(tokenAtPos: Node): CommentOwnerInfo | undefined {
         for (let commentOwner = tokenAtPos; commentOwner; commentOwner = commentOwner.parent) {
@@ -270,32 +271,18 @@ namespace ts.JsDoc {
                     const { parameters } = commentOwner as FunctionDeclaration | MethodDeclaration | ConstructorDeclaration | MethodSignature;
                     return { commentOwner, parameters };
 
-                case SyntaxKind.ClassDeclaration:
-                case SyntaxKind.InterfaceDeclaration:
-                case SyntaxKind.PropertySignature:
-                case SyntaxKind.EnumDeclaration:
-                case SyntaxKind.EnumMember:
-                case SyntaxKind.TypeAliasDeclaration:
-                    return { commentOwner };
-
                 case SyntaxKind.VariableStatement: {
                     const varStatement = <VariableStatement>commentOwner;
                     const varDeclarations = varStatement.declarationList.declarations;
                     const parameters = varDeclarations.length === 1 && varDeclarations[0].initializer
                         ? getParametersFromRightHandSideOfAssignment(varDeclarations[0].initializer)
                         : undefined;
-                    return { commentOwner, parameters };
+                    return parameters ? { commentOwner, parameters } : undefined;
                 }
 
                 case SyntaxKind.SourceFile:
                     return undefined;
 
-                case SyntaxKind.ModuleDeclaration:
-                    // If in walking up the tree, we hit a a nested namespace declaration,
-                    // then we must be somewhere within a dotted namespace name; however we don't
-                    // want to give back a JSDoc template for the 'b' or 'c' in 'namespace a.b.c { }'.
-                    return commentOwner.parent.kind === SyntaxKind.ModuleDeclaration ? undefined : { commentOwner };
-
                 case SyntaxKind.BinaryExpression: {
                     const be = commentOwner as BinaryExpression;
                     if (getSpecialPropertyAssignmentKind(be) === ts.SpecialPropertyAssignmentKind.None) {
@@ -304,6 +291,11 @@ namespace ts.JsDoc {
                     const parameters = isFunctionLike(be.right) ? be.right.parameters : emptyArray;
                     return { commentOwner, parameters };
                 }
+
+                case SyntaxKind.JsxText: {
+                    const parameters: ReadonlyArray<ParameterDeclaration> = emptyArray;
+                    return { commentOwner, parameters };
+                }
             }
         }
     }
diff --git a/tests/cases/fourslash/docCommentTemplateEmptyFile.ts b/tests/cases/fourslash/docCommentTemplateEmptyFile.ts
@@ -3,4 +3,4 @@
 // @Filename: emptyFile.ts
 /////*0*/
 
-verify.noDocCommentTemplateAt("0");
+verify.docCommentTemplateAt("0", 3, "/** */");
diff --git a/tests/cases/fourslash/docCommentTemplateInsideFunctionDeclaration.ts b/tests/cases/fourslash/docCommentTemplateInsideFunctionDeclaration.ts
@@ -3,6 +3,10 @@
 // @Filename: functionDecl.ts
 ////f/*0*/unction /*1*/foo/*2*/(/*3*/) /*4*/{ /*5*/}
 
-for (const marker of test.markers()) {
-    verify.noDocCommentTemplateAt(marker);
-}
+verify.noDocCommentTemplateAt("0");
+
+verify.docCommentTemplateAt("1", 3, "/** */");
+verify.docCommentTemplateAt("2", 3, "/** */");
+verify.docCommentTemplateAt("3", 3, "/** */");
+verify.docCommentTemplateAt("4", 3, "/** */");
+verify.docCommentTemplateAt("5", 3, "/** */");
diff --git a/tests/cases/fourslash/docCommentTemplateJSXText.ts b/tests/cases/fourslash/docCommentTemplateJSXText.ts
@@ -0,0 +1,12 @@
+/// <reference path="fourslash.ts" />
+
+//@Filename: file.tsx
+////
+//// var x = <div>
+//// /*0*/hello/*1*/
+//// /*2*/goodbye/*3*/
+//// </div>;
+
+for (const marker in test.markers()) {
+    verify.noDocCommentTemplateAt(marker);
+}
diff --git a/tests/cases/fourslash/docCommentTemplateNamespacesAndModules02.ts b/tests/cases/fourslash/docCommentTemplateNamespacesAndModules02.ts
@@ -9,6 +9,6 @@
 verify.docCommentTemplateAt("top", /*indentation*/ 3,
 "/** */");
 
-verify.noDocCommentTemplateAt("n2");
+verify.docCommentTemplateAt("n2", 3, "/** */");
 
-verify.noDocCommentTemplateAt("n3");
+verify.docCommentTemplateAt("n3", 3, "/** */");
diff --git a/tests/cases/fourslash/docCommentTemplateRegex.ts b/tests/cases/fourslash/docCommentTemplateRegex.ts
@@ -3,6 +3,8 @@
 // @Filename: regex.ts
 ////var regex = /*0*///*1*/asdf/*2*/ /*3*///*4*/;
 
-for (const marker of test.markers()) {
-    verify.noDocCommentTemplateAt(marker);
-}
+verify.docCommentTemplateAt("0", 3, "/** */");
+verify.noDocCommentTemplateAt("1");
+verify.noDocCommentTemplateAt("2");
+verify.noDocCommentTemplateAt("3");
+verify.docCommentTemplateAt("4", 3, "/** */");
