diff --git a/README.md b/README.md index 9733cbe..d56cc4c 100644 --- a/README.md +++ b/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, diff --git a/package.json b/package.json index 86519db..3a1ffc3 100644 --- a/package.json +++ b/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", diff --git a/src/Config.ts b/src/Config.ts index e103b47..42a42d6 100644 --- a/src/Config.ts +++ b/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 = "you@domain.com"; @@ -87,9 +89,11 @@ export class Config { values.Generic.includeTypeAtReturn = Generic.getConfiguration().get("includeTypeAtReturn", values.Generic.includeTypeAtReturn); values.Generic.boolReturnsTrueFalse = Generic.getConfiguration().get("boolReturnsTrueFalse", values.Generic.boolReturnsTrueFalse); + values.Generic.useBoolRetVal = Generic.getConfiguration().get("useBoolRetVal", values.Generic.useBoolRetVal); values.Generic.briefTemplate = Generic.getConfiguration().get("briefTemplate", values.Generic.briefTemplate); values.Generic.paramTemplate = Generic.getConfiguration().get("paramTemplate", values.Generic.paramTemplate); values.Generic.returnTemplate = Generic.getConfiguration().get("returnTemplate", values.Generic.returnTemplate); + values.Generic.retvalTemplate = Generic.getConfiguration().get("retvalTemplate", values.Generic.retvalTemplate); values.Generic.linesToGet = Generic.getConfiguration().get("linesToGet", values.Generic.linesToGet); values.Generic.authorTag = Generic.getConfiguration().get("authorTag", values.Generic.authorTag); values.Generic.authorName = Generic.getConfiguration().get("authorName", values.Generic.authorName); diff --git a/src/Lang/Cpp/CppDocGen.ts b/src/Lang/Cpp/CppDocGen.ts index 022b372..3cf197d 100644 --- a/src/Lang/Cpp/CppDocGen.ts +++ b/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, ); } diff --git a/src/test/CppTests/ReturnTypes.test.ts b/src/test/CppTests/ReturnTypes.test.ts index 4462e12..257a3f2 100644 --- a/src/test/CppTests/ReturnTypes.test.ts +++ b/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 */");