Add option to use retval for boolean return values

README.md

@@ -224,12 +224,18 @@ Each of them can be configured with its own custom text and you can decide if th
   // The template of the return Doxygen line that is generated. If empty it won't get generated at all.
   "doxdocgen.generic.returnTemplate": "@return {type} ",
 
+  // The template of the retval Doxygen line that is generated. If empty it won't get generated at all.
+  "doxdocgen.generic.retvalTemplate": "@retval {type} ",
+
   // Decide if the values put into {name} should be split according to their casing.
   "doxdocgen.generic.splitCasingSmartText": true,
 
   // Array of keywords that should be removed from the input prior to parsing.
   "doxdocgen.generic.filteredKeywords": [],
 
+  // If enabled, the documentation for a `bool` return value will use `retval` instead of `returns` (only applies if `boolReturnsTrueFalse` is enabled).
+  "doxdocgen.generic.useBoolRetVal": false,
+
   // Substitute {author} with git config --get user.name.
   "doxdocgen.generic.useGitUserName": false,
 

package.json

@@ -144,6 +144,11 @@
           "type": "boolean",
           "default": true
         },
+        "doxdocgen.generic.useBoolRetVal": {
+            "markdownDescription": "If enabled, the documentation for a `bool` return value will use `retval` instead of `returns` (only applies if `#doxdocgen.generic.boolReturnsTrueFalse#` is enabled).",
+            "type": "boolean",
+            "default": false
+          },
         "doxdocgen.generic.briefTemplate": {
           "description": "The template of the brief Doxygen line that is generated. If empty it won't get generated at all.",
           "type": "string",
@@ -159,6 +164,11 @@
           "type": "string",
           "default": "@return {type} "
         },
+        "doxdocgen.generic.retvalTemplate": {
+            "description": "The template of the retval Doxygen line that is generated. If empty it won't get generated at all.",
+            "type": "string",
+            "default": "@retval {type} "
+          },
         "doxdocgen.generic.linesToGet": {
           "description": "How many lines the plugin should look for to find the end of the declaration. Please be aware that setting this value too low could improve the speed of comment generation by a very slim margin but the plugin also may not correctly detect all declarations or definitions anymore.",
           "type": "number",

src/Config.ts

@@ -45,9 +45,11 @@ class Generic {
 
     public includeTypeAtReturn: boolean = true;
     public boolReturnsTrueFalse: boolean = true;
+    public useBoolRetVal: boolean = false;
     public briefTemplate: string = "@brief {text}";
     public paramTemplate: string = "@param {param} ";
     public returnTemplate: string = "@return {type} ";
+    public retvalTemplate: string = "@retval {type} ";
     public linesToGet: number = 20;
     public authorName: string = "your name";
     public authorEmail: string = "[email protected]";
@@ -87,9 +89,11 @@ export class Config {
 
         values.Generic.includeTypeAtReturn = Generic.getConfiguration().get<boolean>("includeTypeAtReturn", values.Generic.includeTypeAtReturn);
         values.Generic.boolReturnsTrueFalse = Generic.getConfiguration().get<boolean>("boolReturnsTrueFalse", values.Generic.boolReturnsTrueFalse);
+        values.Generic.useBoolRetVal = Generic.getConfiguration().get<boolean>("useBoolRetVal", values.Generic.useBoolRetVal);
         values.Generic.briefTemplate = Generic.getConfiguration().get<string>("briefTemplate", values.Generic.briefTemplate);
         values.Generic.paramTemplate = Generic.getConfiguration().get<string>("paramTemplate", values.Generic.paramTemplate);
         values.Generic.returnTemplate = Generic.getConfiguration().get<string>("returnTemplate", values.Generic.returnTemplate);
+        values.Generic.retvalTemplate = Generic.getConfiguration().get<string>("retvalTemplate", values.Generic.retvalTemplate);
         values.Generic.linesToGet = Generic.getConfiguration().get<number>("linesToGet", values.Generic.linesToGet);
         values.Generic.authorTag = Generic.getConfiguration().get<string>("authorTag", values.Generic.authorTag);
         values.Generic.authorName = Generic.getConfiguration().get<string>("authorName", values.Generic.authorName);

src/Lang/Cpp/CppDocGen.ts

@@ -186,6 +186,15 @@ export class CppDocGen implements IDocGen {
         );
     }
 
+    protected useBoolRetVal(): boolean {
+        if (this.cfg.Generic.boolReturnsTrueFalse === false || this.cfg.Generic.useBoolRetVal === false) {
+            return false;
+        }
+
+        return this.func.type.nodes
+            .findIndex((n) => n instanceof CppToken && n.type === CppTokenType.Symbol && n.value === "bool") !== -1;
+    }
+
     protected generateReturnParams(): string[] {
 
         const params: string[] = [];
@@ -419,10 +428,21 @@ export class CppDocGen implements IDocGen {
                 case "return": {
                     if (this.cfg.Generic.returnTemplate.trim().length !== 0 && this.func.type !== null) {
                         const returnParams = this.generateReturnParams();
+
+                        // special case to return return with retval for bool return type
+                        let returnTemplate = this.cfg.Generic.returnTemplate;
+                        if (this.useBoolRetVal()) {
+                            // if template is empty, don't add anything
+                            if (this.cfg.Generic.retvalTemplate.trim().length == 0) {
+                                return;
+                            }
+                            returnTemplate = this.cfg.Generic.retvalTemplate;
+                        }
+
                         templates.generateFromTemplate(
                             lines,
                             this.cfg.typeTemplateReplace,
-                            this.cfg.Generic.returnTemplate,
+                            returnTemplate,
                             returnParams,
                         );
                     }

src/test/CppTests/ReturnTypes.test.ts

@@ -37,6 +37,13 @@ suite("C++ - Return type Tests", () => {
         assert.strictEqual(result, "/**\n * @brief \n * \n * @return int \n */");
     });
 
+    test("Bool with retval", () => {
+        testSetup.cfg.Generic.useBoolRetVal = true;
+        const result = testSetup.SetLine("bool foo();").GetResult();
+        testSetup.cfg.Generic.useBoolRetVal = false;
+        assert.strictEqual(result, "/**\n * @brief \n * \n * @retval true \n * @retval false \n */");
+    });
+
     test("Bool return type", () => {
         const result = testSetup.SetLine("bool foo();").GetResult();
         assert.strictEqual(result, "/**\n * @brief \n * \n * @return true \n * @return false \n */");