feat(42637): Add setting to disable @return generation for JS Doc comments

src/harness/client.ts

@@ -605,7 +605,7 @@ namespace ts.server {
             return notImplemented();
         }
 
-        getDocCommentTemplateAtPosition(_fileName: string, _position: number): TextInsertion {
+        getDocCommentTemplateAtPosition(_fileName: string, _position: number, _options?: DocCommentTemplateOptions): TextInsertion {
             return notImplemented();
         }
 

src/harness/fourslashImpl.ts

@@ -3048,9 +3048,9 @@ namespace FourSlash {
             assert.deepEqual(actualModuleSpecifiers, moduleSpecifiers);
         }
 
-        public verifyDocCommentTemplate(expected: ts.TextInsertion | undefined) {
+        public verifyDocCommentTemplate(expected: ts.TextInsertion | undefined, options?: ts.DocCommentTemplateOptions) {
             const name = "verifyDocCommentTemplate";
-            const actual = this.languageService.getDocCommentTemplateAtPosition(this.activeFile.fileName, this.currentCaretPosition)!;
+            const actual = this.languageService.getDocCommentTemplateAtPosition(this.activeFile.fileName, this.currentCaretPosition, options || { generateReturnInDocTemplate: true })!;
 
             if (expected === undefined) {
                 if (actual) {

src/harness/fourslashInterfaceImpl.ts

@@ -432,9 +432,9 @@ namespace FourSlashInterface {
             this.state.verifyNoMatchingBracePosition(bracePosition);
         }
 
-        public docCommentTemplateAt(marker: string | FourSlash.Marker, expectedOffset: number, expectedText: string) {
+        public docCommentTemplateAt(marker: string | FourSlash.Marker, expectedOffset: number, expectedText: string, options?: ts.DocCommentTemplateOptions) {
             this.state.goToMarker(marker);
-            this.state.verifyDocCommentTemplate({ newText: expectedText.replace(/\r?\n/g, "\r\n"), caretOffset: expectedOffset });
+            this.state.verifyDocCommentTemplate({ newText: expectedText.replace(/\r?\n/g, "\r\n"), caretOffset: expectedOffset }, options);
         }
 
         public noDocCommentTemplateAt(marker: string | FourSlash.Marker) {

src/harness/harnessLanguageService.ts

@@ -558,8 +558,8 @@ namespace Harness.LanguageService {
         getFormattingEditsAfterKeystroke(fileName: string, position: number, key: string, options: ts.FormatCodeOptions): ts.TextChange[] {
             return unwrapJSONCallResult(this.shim.getFormattingEditsAfterKeystroke(fileName, position, key, JSON.stringify(options)));
         }
-        getDocCommentTemplateAtPosition(fileName: string, position: number): ts.TextInsertion {
-            return unwrapJSONCallResult(this.shim.getDocCommentTemplateAtPosition(fileName, position));
+        getDocCommentTemplateAtPosition(fileName: string, position: number, options?: ts.DocCommentTemplateOptions): ts.TextInsertion {
+            return unwrapJSONCallResult(this.shim.getDocCommentTemplateAtPosition(fileName, position, options));
         }
         isValidBraceCompletionAtPosition(fileName: string, position: number, openingBrace: number): boolean {
             return unwrapJSONCallResult(this.shim.isValidBraceCompletionAtPosition(fileName, position, openingBrace));

src/server/protocol.ts

@@ -3273,6 +3273,8 @@ namespace ts.server.protocol {
         readonly provideRefactorNotApplicableReason?: boolean;
         readonly allowRenameOfImportPath?: boolean;
         readonly includePackageJsonAutoImports?: "auto" | "on" | "off";
+
+        readonly generateReturnInDocTemplate?: boolean;
     }
 
     export interface CompilerOptions {

src/server/session.ts

@@ -1641,7 +1641,7 @@ namespace ts.server {
         private getDocCommentTemplate(args: protocol.FileLocationRequestArgs) {
             const { file, languageService } = this.getFileAndLanguageServiceForSyntacticOperation(args);
             const position = this.getPositionInFile(args, file);
-            return languageService.getDocCommentTemplateAtPosition(file, position);
+            return languageService.getDocCommentTemplateAtPosition(file, position, this.getPreferences(file));
         }
 
         private getSpanOfEnclosingComment(args: protocol.SpanOfEnclosingCommentRequestArgs) {

src/services/jsDoc.ts

@@ -251,7 +251,7 @@ namespace ts.JsDoc {
      * @param position The (character-indexed) position in the file where the check should
      * be performed.
      */
-    export function getDocCommentTemplateAtPosition(newLine: string, sourceFile: SourceFile, position: number): TextInsertion | undefined {
+    export function getDocCommentTemplateAtPosition(newLine: string, sourceFile: SourceFile, position: number, options?: DocCommentTemplateOptions): TextInsertion | undefined {
         const tokenAtPos = getTokenAtPosition(sourceFile, position);
         const existingDocComment = findAncestor(tokenAtPos, isJSDoc);
         if (existingDocComment && (existingDocComment.comment !== undefined || length(existingDocComment.tags))) {
@@ -265,7 +265,7 @@ namespace ts.JsDoc {
             return undefined;
         }
 
-        const commentOwnerInfo = getCommentOwnerInfo(tokenAtPos);
+        const commentOwnerInfo = getCommentOwnerInfo(tokenAtPos, options);
         if (!commentOwnerInfo) {
             return undefined;
         }
@@ -325,10 +325,10 @@ namespace ts.JsDoc {
         readonly parameters?: readonly ParameterDeclaration[];
         readonly hasReturn?: boolean;
     }
-    function getCommentOwnerInfo(tokenAtPos: Node): CommentOwnerInfo | undefined {
-        return forEachAncestor(tokenAtPos, getCommentOwnerInfoWorker);
+    function getCommentOwnerInfo(tokenAtPos: Node, options: DocCommentTemplateOptions | undefined): CommentOwnerInfo | undefined {
+        return forEachAncestor(tokenAtPos, n => getCommentOwnerInfoWorker(n, options));
     }
-    function getCommentOwnerInfoWorker(commentOwner: Node): CommentOwnerInfo | undefined | "quit" {
+    function getCommentOwnerInfoWorker(commentOwner: Node, options: DocCommentTemplateOptions | undefined): CommentOwnerInfo | undefined | "quit" {
         switch (commentOwner.kind) {
             case SyntaxKind.FunctionDeclaration:
             case SyntaxKind.FunctionExpression:
@@ -337,10 +337,10 @@ namespace ts.JsDoc {
             case SyntaxKind.MethodSignature:
             case SyntaxKind.ArrowFunction:
                 const host = commentOwner as ArrowFunction | FunctionDeclaration | MethodDeclaration | ConstructorDeclaration | MethodSignature;
-                return { commentOwner, parameters: host.parameters, hasReturn: hasReturn(host) };
+                return { commentOwner, parameters: host.parameters, hasReturn: hasReturn(host, options) };
 
             case SyntaxKind.PropertyAssignment:
-                return getCommentOwnerInfoWorker((commentOwner as PropertyAssignment).initializer);
+                return getCommentOwnerInfoWorker((commentOwner as PropertyAssignment).initializer, options);
 
             case SyntaxKind.ClassDeclaration:
             case SyntaxKind.InterfaceDeclaration:
@@ -357,7 +357,7 @@ namespace ts.JsDoc {
                     ? getRightHandSideOfAssignment(varDeclarations[0].initializer)
                     : undefined;
                 return host
-                    ? { commentOwner, parameters: host.parameters, hasReturn: hasReturn(host) }
+                    ? { commentOwner, parameters: host.parameters, hasReturn: hasReturn(host, options) }
                     : { commentOwner };
             }
 
@@ -371,27 +371,28 @@ namespace ts.JsDoc {
                 return commentOwner.parent.kind === SyntaxKind.ModuleDeclaration ? undefined : { commentOwner };
 
             case SyntaxKind.ExpressionStatement:
-                return getCommentOwnerInfoWorker((commentOwner as ExpressionStatement).expression);
+                return getCommentOwnerInfoWorker((commentOwner as ExpressionStatement).expression, options);
             case SyntaxKind.BinaryExpression: {
                 const be = commentOwner as BinaryExpression;
                 if (getAssignmentDeclarationKind(be) === AssignmentDeclarationKind.None) {
                     return "quit";
                 }
                 return isFunctionLike(be.right)
-                    ? { commentOwner, parameters: be.right.parameters, hasReturn: hasReturn(be.right) }
+                    ? { commentOwner, parameters: be.right.parameters, hasReturn: hasReturn(be.right, options) }
                     : { commentOwner };
             }
             case SyntaxKind.PropertyDeclaration:
                 const init = (commentOwner as PropertyDeclaration).initializer;
                 if (init && (isFunctionExpression(init) || isArrowFunction(init))) {
-                    return { commentOwner, parameters: init.parameters, hasReturn: hasReturn(init) };
+                    return { commentOwner, parameters: init.parameters, hasReturn: hasReturn(init, options) };
                 }
         }
     }
 
-    function hasReturn(node: Node) {
-        return isArrowFunction(node) && isExpression(node.body)
-            || isFunctionLikeDeclaration(node) && node.body && isBlock(node.body) && !!forEachReturnStatement(node.body, n => n);
+    function hasReturn(node: Node, options: DocCommentTemplateOptions | undefined) {
+        return !!options?.generateReturnInDocTemplate &&
+            (isArrowFunction(node) && isExpression(node.body)
+                || isFunctionLikeDeclaration(node) && node.body && isBlock(node.body) && !!forEachReturnStatement(node.body, n => n));
     }
 
     function getRightHandSideOfAssignment(rightHandSide: Expression): FunctionExpression | ArrowFunction | ConstructorDeclaration | undefined {

src/services/services.ts

@@ -2004,8 +2004,8 @@ namespace ts {
                 : Promise.reject("Host does not implement `installPackage`");
         }
 
-        function getDocCommentTemplateAtPosition(fileName: string, position: number): TextInsertion | undefined {
-            return JsDoc.getDocCommentTemplateAtPosition(getNewLineOrDefaultFromHost(host), syntaxTreeCache.getCurrentSourceFile(fileName), position);
+        function getDocCommentTemplateAtPosition(fileName: string, position: number, options?: DocCommentTemplateOptions): TextInsertion | undefined {
+            return JsDoc.getDocCommentTemplateAtPosition(getNewLineOrDefaultFromHost(host), syntaxTreeCache.getCurrentSourceFile(fileName), position, options);
         }
 
         function isValidBraceCompletionAtPosition(fileName: string, position: number, openingBrace: number): boolean {

src/services/shims.ts

@@ -263,7 +263,7 @@ namespace ts {
         /**
          * Returns JSON-encoded value of the type TextInsertion.
          */
-        getDocCommentTemplateAtPosition(fileName: string, position: number): string;
+        getDocCommentTemplateAtPosition(fileName: string, position: number, options?: DocCommentTemplateOptions): string;
 
         /**
          * Returns JSON-encoded boolean to indicate whether we should support brace location
@@ -999,10 +999,10 @@ namespace ts {
                 });
         }
 
-        public getDocCommentTemplateAtPosition(fileName: string, position: number): string {
+        public getDocCommentTemplateAtPosition(fileName: string, position: number, options?: DocCommentTemplateOptions): string {
             return this.forwardJSONCall(
                 `getDocCommentTemplateAtPosition('${fileName}', ${position})`,
-                () => this.languageService.getDocCommentTemplateAtPosition(fileName, position)
+                () => this.languageService.getDocCommentTemplateAtPosition(fileName, position, options)
             );
         }
 

src/services/types.ts

@@ -490,7 +490,7 @@ namespace ts {
         getFormattingEditsForDocument(fileName: string, options: FormatCodeOptions | FormatCodeSettings): TextChange[];
         getFormattingEditsAfterKeystroke(fileName: string, position: number, key: string, options: FormatCodeOptions | FormatCodeSettings): TextChange[];
 
-        getDocCommentTemplateAtPosition(fileName: string, position: number): TextInsertion | undefined;
+        getDocCommentTemplateAtPosition(fileName: string, position: number, options?: DocCommentTemplateOptions): TextInsertion | undefined;
 
         isValidBraceCompletionAtPosition(fileName: string, position: number, openingBrace: number): boolean;
         /**
@@ -1073,6 +1073,10 @@ namespace ts {
         readonly allowRenameOfImportPath?: boolean;
     }
 
+    export interface DocCommentTemplateOptions {
+        readonly generateReturnInDocTemplate?: boolean;
+    }
+
     export interface SignatureHelpParameter {
         name: string;
         documentation: SymbolDisplayPart[];

tests/baselines/reference/api/tsserverlibrary.d.ts

@@ -5555,7 +5555,7 @@ declare namespace ts {
         getFormattingEditsForRange(fileName: string, start: number, end: number, options: FormatCodeOptions | FormatCodeSettings): TextChange[];
         getFormattingEditsForDocument(fileName: string, options: FormatCodeOptions | FormatCodeSettings): TextChange[];
         getFormattingEditsAfterKeystroke(fileName: string, position: number, key: string, options: FormatCodeOptions | FormatCodeSettings): TextChange[];
-        getDocCommentTemplateAtPosition(fileName: string, position: number): TextInsertion | undefined;
+        getDocCommentTemplateAtPosition(fileName: string, position: number, options?: DocCommentTemplateOptions): TextInsertion | undefined;
         isValidBraceCompletionAtPosition(fileName: string, position: number, openingBrace: number): boolean;
         /**
          * This will return a defined result if the position is after the `>` of the opening tag, or somewhere in the text, of a JSXElement with no closing tag.
@@ -6020,6 +6020,9 @@ declare namespace ts {
     interface RenameInfoOptions {
         readonly allowRenameOfImportPath?: boolean;
     }
+    interface DocCommentTemplateOptions {
+        readonly generateReturnInDocTemplate?: boolean;
+    }
     interface SignatureHelpParameter {
         name: string;
         documentation: SymbolDisplayPart[];
@@ -9046,6 +9049,7 @@ declare namespace ts.server.protocol {
         readonly provideRefactorNotApplicableReason?: boolean;
         readonly allowRenameOfImportPath?: boolean;
         readonly includePackageJsonAutoImports?: "auto" | "on" | "off";
+        readonly generateReturnInDocTemplate?: boolean;
     }
     interface CompilerOptions {
         allowJs?: boolean;

tests/baselines/reference/api/typescript.d.ts

@@ -5555,7 +5555,7 @@ declare namespace ts {
         getFormattingEditsForRange(fileName: string, start: number, end: number, options: FormatCodeOptions | FormatCodeSettings): TextChange[];
         getFormattingEditsForDocument(fileName: string, options: FormatCodeOptions | FormatCodeSettings): TextChange[];
         getFormattingEditsAfterKeystroke(fileName: string, position: number, key: string, options: FormatCodeOptions | FormatCodeSettings): TextChange[];
-        getDocCommentTemplateAtPosition(fileName: string, position: number): TextInsertion | undefined;
+        getDocCommentTemplateAtPosition(fileName: string, position: number, options?: DocCommentTemplateOptions): TextInsertion | undefined;
         isValidBraceCompletionAtPosition(fileName: string, position: number, openingBrace: number): boolean;
         /**
          * This will return a defined result if the position is after the `>` of the opening tag, or somewhere in the text, of a JSXElement with no closing tag.
@@ -6020,6 +6020,9 @@ declare namespace ts {
     interface RenameInfoOptions {
         readonly allowRenameOfImportPath?: boolean;
     }
+    interface DocCommentTemplateOptions {
+        readonly generateReturnInDocTemplate?: boolean;
+    }
     interface SignatureHelpParameter {
         name: string;
         documentation: SymbolDisplayPart[];

tests/cases/fourslash/docCommentTemplateReturnsTag2.ts

@@ -0,0 +1,21 @@
+/// <reference path='fourslash.ts' />
+
+/////*0*/
+////function f1(x: number, y: number) {
+////    return 1;
+////}
+
+verify.docCommentTemplateAt("0", 8,
+   `/**
+ * 
+ * @param x
+ * @param y
+ * @returns
+ */`, { generateReturnInDocTemplate: true });
+
+verify.docCommentTemplateAt("0", 8,
+   `/**
+ * 
+ * @param x
+ * @param y
+ */`, { generateReturnInDocTemplate: false });

tests/cases/fourslash/fourslash.ts

@@ -328,7 +328,7 @@ declare namespace FourSlashInterface {
         todoCommentsInCurrentFile(descriptors: string[]): void;
         matchingBracePositionInCurrentFile(bracePosition: number, expectedMatchPosition: number): void;
         noMatchingBracePositionInCurrentFile(bracePosition: number): void;
-        docCommentTemplateAt(markerName: string | FourSlashInterface.Marker, expectedOffset: number, expectedText: string): void;
+        docCommentTemplateAt(markerName: string | FourSlashInterface.Marker, expectedOffset: number, expectedText: string, options?: VerifyDocCommentTemplateOptions): void;
         noDocCommentTemplateAt(markerName: string | FourSlashInterface.Marker): void;
         rangeAfterCodeFix(expectedText: string, includeWhiteSpace?: boolean, errorCode?: number, index?: number): void;
         codeFixAll(options: { fixId: string, fixAllDescription: string, newFileContent: NewFileContent, commands?: {}[] }): void;
@@ -664,6 +664,10 @@ declare namespace FourSlashInterface {
         overrideSelectedItemIndex?: number;
     }
 
+    interface VerifyDocCommentTemplateOptions {
+        generateReturnInDocTemplate?: boolean;
+    }
+
     export type SignatureHelpTriggerReason =
         | SignatureHelpInvokedReason
         | SignatureHelpCharacterTypedReason