Adding doxygen comment generation (#9656)

Author: jiefangli

Extension/package.json

@@ -2333,6 +2333,24 @@
           "markdownDescription": "%c_cpp.configuration.simplifyStructuredComments.markdownDescription%",
           "scope": "application"
         },
+        "C_Cpp.autocompleteDoxygenComment":{
+          "type":"boolean",
+          "default":true,
+          "description": "%c_cpp.configuration.autocompleteDoxygenComment.description%",
+          "scope": "resource"
+        },
+        "C_Cpp.generatedDoxygenCommentStyle": {
+          "type":"string",
+          "enum":[
+            "///",
+            "/**",
+            "/*!",
+            "//!"
+          ],
+          "default":"/**",
+          "description": "%c_cpp.configuration.generatedDoxygenCommentStyle.description%",
+          "scope": "resource"
+        },
         "C_Cpp.commentContinuationPatterns": {
           "type": "array",
           "default": [
@@ -2876,7 +2894,13 @@
         "command": "C_Cpp.AddDebugConfiguration",
         "title": "%c_cpp.command.AddDebugConfiguration.title%",
         "category": "C/C++",
-        "icon": "$(debug-configure)"
+        "icon": "$(debug-configure)"      
+      },
+      {
+        "command": "C_Cpp.GenerateDoxygenComment", 
+        "title":"%c_cpp.command.GenerateDoxygenComment.title%",
+        "category":"C/C++"
+                   
       }
     ],
     "keybindings": [
@@ -4901,6 +4925,11 @@
           "command": "C_Cpp.AddDebugConfiguration",
           "when": "editorLangId == 'c' && config.C_Cpp.debugShortcut && BuildAndDebug.isSourceFile && BuildAndDebug.isFolderOpen || editorLangId == 'cpp' && config.C_Cpp.debugShortcut && BuildAndDebug.isSourceFile && BuildAndDebug.isFolderOpen || editorLangId == 'cuda-cpp' && config.C_Cpp.debugShortcut && BuildAndDebug.isSourceFile && BuildAndDebug.isFolderOpen",
           "group": "custom2@3"
+        },
+        {
+          "command": "C_Cpp.GenerateDoxygenComment",
+          "when": "editorLangId == 'c' || editorLangId == 'cpp' || editorLangId == 'cuda-cpp'",
+          "group": "custom2@3"
         }
       ],
       "commandPalette": [

Extension/package.nls.json

@@ -28,6 +28,7 @@
     "c_cpp.command.BuildAndDebugFile.title": "Debug C/C++ File",
     "c_cpp.command.BuildAndRunFile.title": "Run C/C++ File",
     "c_cpp.command.AddDebugConfiguration.title": "Add Debug Configuration",
+    "c_cpp.command.GenerateDoxygenComment.title": "Generate Doxygen Comment",
     "c_cpp.configuration.maxConcurrentThreads.markdownDescription": { "message": "The maximum number of concurrent threads to use for language service processing. The value is a hint and may not always be used. The default of `null` (empty) uses the number of logical processors available.", "comment": [ "Markdown text between `` should not be translated or localized (they represent literal text) and the capitalization, spacing, and punctuation (including the ``) should not be altered." ] },
     "c_cpp.configuration.maxCachedProcesses.markdownDescription": { "message": "The maximum number of cached processes to use for language service processing. The default of `null` (empty) uses twice the number of logical processors available.", "comment": [ "Markdown text between `` should not be translated or localized (they represent literal text) and the capitalization, spacing, and punctuation (including the ``) should not be altered." ] },
     "c_cpp.configuration.maxMemory.markdownDescription": { "message": "The maximum memory (in MB) available for language service processing. Fewer processes will be cached and run concurrently after this memory usage is exceeded. The default of `null` (empty) uses the system's free memory.", "comment": [ "Markdown text between `` should not be translated or localized (they represent literal text) and the capitalization, spacing, and punctuation (including the ``) should not be altered." ] },
@@ -184,6 +185,8 @@
     "c_cpp.configuration.preferredPathSeparator.markdownDescription": { "message": "The character used as a path separator for `#include` auto-completion results.", "comment": [ "Markdown text between `` should not be translated or localized (they represent literal text) and the capitalization, spacing, and punctuation (including the ``) should not be altered." ] },
     "c_cpp.configuration.simplifyStructuredComments.markdownDescription": { "message": "If `true`, tooltips of hover and auto-complete will only display certain labels of structured comments. Otherwise, all comments are displayed.", "comment": [ "Markdown text between `` should not be translated or localized (they represent literal text) and the capitalization, spacing, and punctuation (including the ``) should not be altered." ] },
     "c_cpp.configuration.commentContinuationPatterns.items.anyof.string.markdownDescription": { "message": "The pattern that begins a multiline or single line comment block. The continuation pattern defaults to ` * ` for multiline comment blocks or this string for single line comment blocks.", "comment": [ "Markdown text between `` should not be translated or localized (they represent literal text) and the capitalization, spacing, and punctuation (including the ``) should not be altered." ] },
+    "c_cpp.configuration.autocompleteDoxygenComment.description":  "Controls whether to automatically insert the Doxygen comment after typing the chosen comment style.",
+    "c_cpp.configuration.generatedDoxygenCommentStyle.description": "The string of characters used as the starting line of the Doxygen comment.",
     "c_cpp.configuration.commentContinuationPatterns.items.anyof.object.begin.description": "The pattern that begins a multiline or single line comment block.",
     "c_cpp.configuration.commentContinuationPatterns.items.anyof.object.continue.description": "The text that will be inserted on the next line when Enter is pressed inside a multiline or single line comment block.",
     "c_cpp.configuration.commentContinuationPatterns.description": "Defines the editor behavior for when the Enter key is pressed inside a multiline or single line comment block.",

Extension/src/LanguageServer/client.ts

@@ -401,6 +401,22 @@ interface GoToDirectiveInGroupParams {
     next: boolean;
 };
 
+export interface GenerateDoxygenCommentParams {
+    uri: string;
+    position: Position;
+    isCodeAction: boolean;
+    isCursorAboveSignatureLine: boolean;
+}
+
+export interface GenerateDoxygenCommentResult {
+    contents: string;
+    initPosition: Position;
+    finalInsertionLine: number;
+    finalCursorPosition: Position;
+    fileVersion: number;
+    isCursorAboveSignatureLine: boolean;
+}
+
 interface SetTemporaryTextDocumentLanguageParams {
     path: string;
     isC: boolean;
@@ -444,6 +460,7 @@ export const FormatDocumentRequest: RequestType<FormatParams, TextEdit[], void>
 export const FormatRangeRequest: RequestType<FormatParams, TextEdit[], void> = new RequestType<FormatParams, TextEdit[], void>('cpptools/formatRange');
 export const FormatOnTypeRequest: RequestType<FormatParams, TextEdit[], void> = new RequestType<FormatParams, TextEdit[], void>('cpptools/formatOnType');
 const GoToDirectiveInGroupRequest: RequestType<GoToDirectiveInGroupParams, Position | undefined, void> = new RequestType<GoToDirectiveInGroupParams, Position | undefined, void>('cpptools/goToDirectiveInGroup');
+const GenerateDoxygenCommentRequest: RequestType<GenerateDoxygenCommentParams, GenerateDoxygenCommentResult | undefined, void> = new RequestType<GenerateDoxygenCommentParams, GenerateDoxygenCommentResult, void>('cpptools/generateDoxygenComment');
 
 // Notifications to the server
 const DidOpenNotification: NotificationType<DidOpenTextDocumentParams> = new NotificationType<DidOpenTextDocumentParams>('textDocument/didOpen');
@@ -500,6 +517,8 @@ const IntelliSenseSetupNotification: NotificationType<IntelliSenseSetup> = new N
 const SetTemporaryTextDocumentLanguageNotification: NotificationType<SetTemporaryTextDocumentLanguageParams> = new NotificationType<SetTemporaryTextDocumentLanguageParams>('cpptools/setTemporaryTextDocumentLanguage');
 const ReportCodeAnalysisProcessedNotification: NotificationType<number> = new NotificationType<number>('cpptools/reportCodeAnalysisProcessed');
 const ReportCodeAnalysisTotalNotification: NotificationType<number> = new NotificationType<number>('cpptools/reportCodeAnalysisTotal');
+const DoxygenCommentGeneratedNotification: NotificationType<GenerateDoxygenCommentResult> = new NotificationType<GenerateDoxygenCommentResult>('cpptools/insertDoxygenComment');
+
 let failureMessageShown: boolean = false;
 
 export interface ReferencesCancellationState {
@@ -647,6 +666,7 @@ export interface Client {
     handleConfigurationEditUICommand(viewColumn?: vscode.ViewColumn): void;
     handleAddToIncludePathCommand(path: string): void;
     handleGoToDirectiveInGroup(next: boolean): Promise<void>;
+    handleGenerateDoxygenComment(initCursorLine: number | undefined, initCursorColumn: number | undefined, line: number | undefined, column: number | undefined, insertNewLineAtBeginning: boolean | undefined): Promise<void>;
     handleCheckForCompiler(): Promise<void>;
     handleRunCodeAnalysisOnActiveFile(): Promise<void>;
     handleRunCodeAnalysisOnOpenFiles(): Promise<void>;
@@ -977,6 +997,8 @@ export class DefaultClient implements Client {
         const settings_suggestSnippets: (boolean | undefined)[] = [];
         const settings_exclusionPolicy: (string | undefined)[] = [];
         const settings_preferredPathSeparator: (string | undefined)[] = [];
+        const settings_generatedDoxygenCommentStyle: (string | undefined)[] = [];
+        const settings_autocompleteDoxygenComment: (boolean | undefined)[] = [];
         const settings_defaultSystemIncludePath: (string[] | undefined)[] = [];
         const settings_intelliSenseCachePath: (string | undefined)[] = [];
         const settings_intelliSenseCacheSize: (number | undefined)[] = [];
@@ -1144,6 +1166,8 @@ export class DefaultClient implements Client {
                 settings_suggestSnippets.push(setting.suggestSnippets);
                 settings_exclusionPolicy.push(setting.exclusionPolicy);
                 settings_preferredPathSeparator.push(setting.preferredPathSeparator);
+                settings_generatedDoxygenCommentStyle.push(setting.generatedDoxygenCommentStyle);
+                settings_autocompleteDoxygenComment.push(setting.autocompleteDoxygenComment);
                 settings_defaultSystemIncludePath.push(setting.defaultSystemIncludePath);
                 settings_intelliSenseCachePath.push(util.resolveCachePath(setting.intelliSenseCachePath, this.AdditionalEnvironment));
                 settings_intelliSenseCacheSize.push(setting.intelliSenseCacheSize);
@@ -1328,6 +1352,8 @@ export class DefaultClient implements Client {
                 enhancedColorization: settings_enhancedColorization,
                 suggestSnippets: settings_suggestSnippets,
                 simplifyStructuredComments: workspaceSettings.simplifyStructuredComments,
+                generatedDoxygenCommentStyle: settings_generatedDoxygenCommentStyle,
+                autocompleteDoxygenComment: settings_autocompleteDoxygenComment,
                 loggingLevel: workspaceSettings.loggingLevel,
                 workspaceParsingPriority: workspaceSettings.workspaceParsingPriority,
                 workspaceSymbols: workspaceSettings.workspaceSymbols,
@@ -2131,6 +2157,7 @@ export class DefaultClient implements Client {
         this.languageClient.onNotification(SetTemporaryTextDocumentLanguageNotification, (e) => this.setTemporaryTextDocumentLanguage(e));
         this.languageClient.onNotification(ReportCodeAnalysisProcessedNotification, (e) => this.updateCodeAnalysisProcessed(e));
         this.languageClient.onNotification(ReportCodeAnalysisTotalNotification, (e) => this.updateCodeAnalysisTotal(e));
+        this.languageClient.onNotification(DoxygenCommentGeneratedNotification, (e) => this.insertDoxygenComment(e));
         setupOutputHandlers();
     }
 
@@ -2615,6 +2642,32 @@ export class DefaultClient implements Client {
         this.model.codeAnalysisTotal.Value = total;
     }
 
+    private async insertDoxygenComment(result: GenerateDoxygenCommentResult): Promise<void> {
+        const editor: vscode.TextEditor | undefined = vscode.window.activeTextEditor;
+        if (!editor) {
+            return;
+        }
+        const currentFileVersion: number | undefined = openFileVersions.get(editor.document.uri.toString());
+        // Insert the comment only if the cursor has not moved
+        if (result.fileVersion === currentFileVersion &&
+            result.initPosition.line === editor.selection.active.line &&
+            result.initPosition.character === editor.selection.active.character &&
+            result.contents.length > 1) {
+            const workspaceEdit: vscode.WorkspaceEdit = new vscode.WorkspaceEdit();
+            const edits: vscode.TextEdit[] = [];
+            const maxColumn: number = 99999999;
+            const newRange: vscode.Range = new vscode.Range(editor.selection.start.line, 0, editor.selection.end.line, maxColumn);
+            edits.push(new vscode.TextEdit(newRange, result?.contents));
+            workspaceEdit.set(editor.document.uri, edits);
+            await vscode.workspace.applyEdit(workspaceEdit);
+
+            // Set the cursor position after @brief
+            const newPosition: vscode.Position = new vscode.Position(result.finalCursorPosition.line, result.finalCursorPosition.character);
+            const newSelection: vscode.Selection = new vscode.Selection(newPosition, newPosition);
+            editor.selection = newSelection;
+        }
+    }
+
     private doneInitialCustomBrowseConfigurationCheck: boolean = false;
 
     private onConfigurationsChanged(cppProperties: configs.CppProperties): void {
@@ -2960,7 +3013,6 @@ export class DefaultClient implements Client {
                 position: editor.selection.active,
                 next: next
             };
-
             await this.awaitUntilLanguageClientReady();
             const response: Position | undefined = await this.languageClient.sendRequest(GoToDirectiveInGroupRequest, params);
             if (response) {
@@ -2977,6 +3029,75 @@ export class DefaultClient implements Client {
         }
     }
 
+    public async handleGenerateDoxygenComment(initCursorLine: number | undefined, initCursorColumn: number | undefined, adjustedLine: number | undefined, adjustedColmn: number | undefined, isCursorAboveSignatureLine: boolean): Promise<void> {
+        const editor: vscode.TextEditor | undefined = vscode.window.activeTextEditor;
+        if (!editor) {
+            return;
+        }
+
+        if (editor.document.uri.scheme !== "file") {
+            return;
+        }
+
+        if (!(editor.document.languageId === "c" || editor.document.languageId === "cpp" || editor.document.languageId === "cuda-cpp")) {
+            return;
+        }
+
+        const isCodeAction: boolean = (adjustedLine !== undefined && adjustedLine !== undefined);
+        const initCursorPosition: vscode.Position = isCodeAction ? new vscode.Position(initCursorLine ?? 0, initCursorColumn ?? 0) : editor.selection.active;
+        const params: GenerateDoxygenCommentParams = {
+            uri: editor.document.uri.toString(),
+            position: isCodeAction ? new vscode.Position(adjustedLine ?? 0, adjustedColmn ?? 0) : editor.selection.active,
+            isCodeAction: isCodeAction,
+            isCursorAboveSignatureLine: isCursorAboveSignatureLine
+        };
+        await this.awaitUntilLanguageClientReady();
+        const currentFileVersion: number | undefined = openFileVersions.get(params.uri);
+        if (currentFileVersion === undefined) {
+            return;
+        }
+        const result: GenerateDoxygenCommentResult | undefined = await this.languageClient.sendRequest(GenerateDoxygenCommentRequest, params);
+        // Insert the comment only if the comment has contents and the cursor has not moved
+        if (result !== undefined &&
+            initCursorPosition.line === editor.selection.active.line &&
+            initCursorPosition.character === editor.selection.active.character &&
+            result.fileVersion !== undefined &&
+            result.fileVersion === currentFileVersion &&
+            result.contents && result.contents.length > 1) {
+            const workspaceEdit: vscode.WorkspaceEdit = new vscode.WorkspaceEdit();
+            const edits: vscode.TextEdit[] = [];
+            const maxColumn: number = 99999999;
+            let newRange: vscode.Range;
+            const cursorOnEmptyLineAboveSignature: boolean = result.isCursorAboveSignatureLine;
+            // The reason why we need to set different range is because if cursor is immediately above the signature line, we want the comments to be inserted at the line of cursor and to replace everything on the line.
+            // If the cursor is on the signature line or is inside the boby, the comment will be inserted on the same line of the signature and it shouldn't replace the content of the signature line.
+            if (cursorOnEmptyLineAboveSignature) {
+                if (isCodeAction) {
+                    // The reson why we cannot use finalInsertionLine is because the line number sent from the result is not correct.
+                    // In most cases, the finalInsertionLine is the line of the signature line.
+                    newRange = new vscode.Range(initCursorPosition.line, 0, initCursorPosition.line, maxColumn);
+                } else {
+                    newRange = new vscode.Range(result.finalInsertionLine, 0, result.finalInsertionLine, maxColumn);
+                }
+            } else {
+                newRange = new vscode.Range(result.finalInsertionLine, 0, result.finalInsertionLine, 0);
+            }
+            edits.push(new vscode.TextEdit(newRange, result?.contents));
+            workspaceEdit.set(editor.document.uri, edits);
+            await vscode.workspace.applyEdit(workspaceEdit);
+            // Set the cursor position after @brief
+            let newPosition: vscode.Position;
+            if (cursorOnEmptyLineAboveSignature && isCodeAction) {
+                newPosition = new vscode.Position(result.finalCursorPosition.line - 1, result.finalCursorPosition.character);
+            } else {
+                newPosition = new vscode.Position(result.finalCursorPosition.line, result.finalCursorPosition.character);
+            }
+            const newSelection: vscode.Selection = new vscode.Selection(newPosition, newPosition);
+            editor.selection = newSelection;
+        }
+
+    }
+
     public async handleCheckForCompiler(): Promise<void> {
         await this.awaitUntilLanguageClientReady();
         const compilers: configs.KnownCompiler[] | undefined = await this.getKnownCompilers();
@@ -3017,7 +3138,7 @@ export class DefaultClient implements Client {
 
     public async handleRunCodeAnalysisOnAllFiles(): Promise<void> {
         await this.awaitUntilLanguageClientReady();
-        this.languageClient.sendNotification(CodeAnalysisNotification, { scope:  CodeAnalysisScope.AllFiles });
+        this.languageClient.sendNotification(CodeAnalysisNotification, { scope: CodeAnalysisScope.AllFiles });
     }
 
     public async handleRemoveAllCodeAnalysisProblems(): Promise<void> {
@@ -3254,6 +3375,7 @@ class NullClient implements Client {
     handleConfigurationEditUICommand(viewColumn?: vscode.ViewColumn): void { }
     handleAddToIncludePathCommand(path: string): void { }
     handleGoToDirectiveInGroup(next: boolean): Promise<void> { return Promise.resolve(); }
+    handleGenerateDoxygenComment(): Promise<void> { return Promise.resolve(); }
     handleCheckForCompiler(): Promise<void> { return Promise.resolve(); }
     handleRunCodeAnalysisOnActiveFile(): Promise<void> { return Promise.resolve(); }
     handleRunCodeAnalysisOnOpenFiles(): Promise<void> { return Promise.resolve(); }