From 0ebfa5bd12e529d8febe73c85d3bf48c4d4997e8 Mon Sep 17 00:00:00 2001 From: Rowan Goemans Date: Sat, 14 Oct 2017 22:29:02 +0200 Subject: -- Added extensive templating the be able to generated different types of doxygen comment. --- package.json | 59 +++++++++-- src/CodeParser/CParser.ts | 19 ++-- src/CodeParser/CodeParserController.ts | 31 +++--- src/Config.ts | 13 ++- src/DocGen/CGen.ts | 172 ++++++++++++++++----------------- src/DocGen/DocGen.ts | 19 +--- 6 files changed, 178 insertions(+), 135 deletions(-) diff --git a/package.json b/package.json index 4ea2631..f38fef7 100644 --- a/package.json +++ b/package.json @@ -18,19 +18,60 @@ "type": "object", "title": "Doxygen Documentation Generator Settings", "properties": { - "doxdocgen.generic.commentStart": { - "description": "Doxygen comment start indicator. Default ist /** but Qt style with /*! is also valid.", + "doxdocgen.generic.triggerSequence": { + "description": "Doxygen comment trigger. This character sequence triggers generation of DoxyGen comments.", "type": "string", - "default": "/**", - "enum": [ - "/**", - "/*!" - ] + "default": "/**" }, - "doxdocgen.generic.generateReturnType": { - "description": "Insert return type into generated documentation", + "doxdocgen.generic.firstLine": { + "description": "The first line of the comment that gets generated. If empty it won't get generated at all.", + "type": "string", + "default": "/**" + }, + "doxdocgen.generic.commentPrefix": { + "description": "The pre fix that is used for each comment line.", + "type": "string", + "default": " * " + }, + "doxdocgen.generic.lastLine": { + "description": "The last line of the comment that gets generated. If empty it won't get generated at all.", + "type": "string", + "default": "**/" + }, + "doxdocgen.generic.newLineAfterBrief": { + "description": "Whether to insert a newline after a brief.", "type": "boolean", "default": true + }, + "doxdocgen.generic.newLineAfterParams": { + "description": "Whether to insert a newline after the params.", + "type": "boolean", + "default": false + }, + "doxdocgen.generic.newLineAfterTParams": { + "description": "Whether to insert a newline after the template params.", + "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", + "default": "@brief " + }, + "doxdocgen.generic.paramTemplate": { + "description": "The template of the param DoxyGen line(s) that are generated. If empty it won't get generated at all.", + "type": "string", + "default": "@param {param} " + }, + "doxdocgen.generic.tparamTemplate": { + "description": "The template of the template parameter DoxyGen line(s) that are generated. If empty it won't get generated at all.", + "type": "string", + "default": "@tparam {param} " + }, + "doxdocgen.generic.returnTemplate": { + "description": "The template of the return DoxyGen line that is generated. If empty it won't get generated at all.", + "type": "string", + "default": "@return {param} " } } } diff --git a/src/CodeParser/CParser.ts b/src/CodeParser/CParser.ts index 4889de6..12ed169 100644 --- a/src/CodeParser/CParser.ts +++ b/src/CodeParser/CParser.ts @@ -35,8 +35,9 @@ export default class CParser implements ICodeParser { const returnValue: string[] = this.getReturn(method); const params: string[] = this.getParams(method); + const tparams: string[] = this.getTemplateParams(method); - const cppGenerator: IDocGen = new Generator(this.activeEditor, this.activeSelection, params, returnValue); + const cppGenerator: IDocGen = new Generator(this.activeEditor, this.activeSelection, params, tparams, returnValue); return cppGenerator; } @@ -84,7 +85,7 @@ export default class CParser implements ICodeParser { const retVals: string[] = []; // Remove the compiler keywords from the signature - const sign: string = method.replace(/(static)|(inline)|(friend)|(virtual)|(extern)|(explicit)/g, ""); + const sign: string = method.replace(/(static)|(inline)|(friend)|(virtual)|(extern)|(explicit)|(const)/g, ""); // Remove the parameters from the signature const returnSignature = sign.slice(0, sign.indexOf("(")).trim(); @@ -106,14 +107,6 @@ export default class CParser implements ICodeParser { break; } - // Don't generate return type if the user doesn't wish to do it - if (!workspace.getConfiguration(ConfigType.generic).get(Config.generateReturnType, true) && - retVals.length > 0) { - retVals.length = 0; - retVals.push(" "); - return retVals; - } - return retVals; } @@ -139,4 +132,10 @@ export default class CParser implements ICodeParser { return paramArr; } + + protected getTemplateParams(method: string): string[] { + // Todo implement parsing of template parameters. + const tparams: string[] = []; + return tparams; + } } diff --git a/src/CodeParser/CodeParserController.ts b/src/CodeParser/CodeParserController.ts index 49d4082..0a80e77 100644 --- a/src/CodeParser/CodeParserController.ts +++ b/src/CodeParser/CodeParserController.ts @@ -1,4 +1,4 @@ -import { Disposable, Position, TextDocumentContentChangeEvent, TextEditor, TextLine, window, workspace } from "vscode"; +import { Disposable, Position, Range, TextDocumentContentChangeEvent, TextEditor, TextLine, window, workspace } from "vscode"; import { Config, ConfigType } from "../Config"; import CodeParser from "./CodeParser"; import CParser from "./CParser"; @@ -13,7 +13,7 @@ import CppParser from "./CppParser"; */ export default class CodeParserController { private disposable: Disposable; - private indicators: string[] = []; + private triggerSequence: string; /** * Creates an instance of CodeParserController @@ -51,8 +51,7 @@ export default class CodeParserController { ***************************************************************************/ private readConfig() { - this.indicators.pop(); - this.indicators.push(workspace.getConfiguration(ConfigType.generic).get(Config.commentStart, "/**")); + this.triggerSequence = workspace.getConfiguration(ConfigType.generic).get(Config.triggerSequence, "/**"); } private check(activeEditor: TextEditor, event: TextDocumentContentChangeEvent): boolean { @@ -64,7 +63,7 @@ export default class CodeParserController { const activeChar: string = activeLine.text.charAt(activeSelection.character); const startsWith: boolean = event.text.startsWith("\n") || event.text.startsWith("\r\n"); - // Check if enter was pressed. Note the ! + // Check if enter was pressed. Note the ! if (!((activeChar === "") && startsWith)) { return false; } @@ -72,14 +71,7 @@ export default class CodeParserController { const cont: string = activeLine.text.trim(); let found: boolean = false; - this.indicators.forEach((element: string) => { - if (element === cont) { // Compare the content from the line with the valid indicators - found = true; - return; - } - }); - - return found; + return this.triggerSequence === cont; } private onEvent(activeEditor: TextEditor, event: TextDocumentContentChangeEvent) { @@ -102,6 +94,17 @@ export default class CodeParserController { console.log("No comments can be generated for language: " + lang); return null; } - parser.Parse(activeEditor, event).GenerateDoc(); + + const currentPos: Position = window.activeTextEditor.selection.active; + const startReplace: Position = new Position(currentPos.line, currentPos.character - this.triggerSequence.length); + + let endReplace: Position = new Position(currentPos.line, currentPos.character); + const nextLineText: String = window.activeTextEditor.document.lineAt(endReplace.line + 1).text; + // VSCode may enter a * on itself, we don't want that in our comment. + if (nextLineText.trim() === "*") { + endReplace = new Position(currentPos.line + 1, nextLineText.length); + } + + parser.Parse(activeEditor, event).GenerateDoc(new Range(startReplace, endReplace)); } } diff --git a/src/Config.ts b/src/Config.ts index 2e449cf..f8011c3 100644 --- a/src/Config.ts +++ b/src/Config.ts @@ -3,6 +3,15 @@ export enum ConfigType { } export enum Config { - commentStart = "commentStart", - generateReturnType = "generateReturnType", + triggerSequence = "triggerSequence", + firstLine = "firstLine", + commentPrefix = "commentPrefix", + lastLine = "lastLine", + newLineAfterBrief = "newLineAfterBrief", + newLineAfterParams = "newLineAfterParams", + newLineAfterTParams = "newLineAfterTParams", + briefTemplate = "briefTemplate", + paramTemplate = "paramTemplate", + tparamTemplate = "tparamTemplate", + returnTemplate = "returnTemplate", } diff --git a/src/DocGen/CGen.ts b/src/DocGen/CGen.ts index 426bb26..97ba12e 100644 --- a/src/DocGen/CGen.ts +++ b/src/DocGen/CGen.ts @@ -1,66 +1,76 @@ -import { Position, Range, Selection, TextEditor, TextLine, WorkspaceEdit } from "vscode"; -import { DoxygenCommands, IDocGen } from "./DocGen"; +import { Position, Range, Selection, TextEditor, TextLine, WorkspaceEdit, workspace } from "vscode"; +import { IDocGen } from "./DocGen"; +import { Config, ConfigType } from "../Config"; export default class CGen implements IDocGen { - protected lineStart: string; - protected endComment: string; - protected commandIndicator: string; - protected spaceAfterCommand: string; + protected firstLine: string; + protected commentPrefix: string; + protected lastLine: string; + protected newLineAfterBrief: boolean; + protected newLineAfterParams: boolean; + protected newLineAfterTParams: boolean; + protected briefTemplate: string; + protected paramTemplate: string; + protected tparamTemplate: string; + protected returnTemplate: string; + + protected templateReplaceString: string; + protected activeEditor: TextEditor; protected position: Position; - protected comment: string; protected retVals: string[]; protected params: string[]; + protected tparams: string[]; /** * @param {TextEditor} actEdit Active editor window * @param {Position} cursorPosition Where the cursor of the user currently is * @param {string[]} param The parameter names of the method extracted by the parser + * @param {string[]} tparam The template parameter names of the method extracted by the parser. * @param {string[]} returnVals The return values extracted by the parser */ - public constructor(actEdit: TextEditor, cursorPosition: Position, param: string[], returnVals: string[]) { + public constructor(actEdit: TextEditor, cursorPosition: Position, param: string[], tparam: string[], returnVals: string[]) { this.activeEditor = actEdit; this.position = cursorPosition; - this.comment = "\n"; // Add the new line after the comment indicator + this.templateReplaceString = "{param}"; this.params = param; + this.tparams = tparam; this.retVals = returnVals; } /** * @inheritdoc */ - public GenerateDoc() { + public GenerateDoc(rangeToReplace: Range) { this.readConfig(); - this.generateComment(); - - const oldPos: Position = this.position; + const comment: string = this.generateComment(); - const active: Position = this.activeEditor.selection.active; - const anchor: Position = new Position(active.line + 1, active.character); // Start at the next line - const replaceSelection = new Selection(anchor, active); this.activeEditor.edit((editBuilder) => { - editBuilder.replace(replaceSelection, this.comment); // Insert the comment + editBuilder.replace(rangeToReplace, comment); // Insert the comment }); // Set cursor after brief command - this.setCursor(oldPos.line + 3, oldPos.character); - const newSelectActive = new Position(oldPos.line + 3, oldPos.character + DoxygenCommands.detailed.length); - const newSelectPos = new Position(oldPos.line + 3, oldPos.character); - this.activeEditor.selection = new Selection(newSelectPos, newSelectActive); + this.setCursorToBrief(rangeToReplace.start.line, rangeToReplace.start.character); } /*************************************************************************** Implementation ***************************************************************************/ - protected readConfig() { - this.lineStart = " * "; // TODO: make this customizable - this.endComment = "*/"; // TODO: make this customizable - this.commandIndicator = "@"; // TODO: make this customizable - this.spaceAfterCommand = " "; // TODO: make this customizable + protected readConfig() { + this.firstLine = workspace.getConfiguration(ConfigType.generic).get(Config.firstLine, ""); + this.commentPrefix = workspace.getConfiguration(ConfigType.generic).get(Config.commentPrefix, ""); + this.lastLine = workspace.getConfiguration(ConfigType.generic).get(Config.lastLine, ""); + this.newLineAfterBrief = workspace.getConfiguration(ConfigType.generic).get(Config.newLineAfterBrief, true); + this.newLineAfterParams = workspace.getConfiguration(ConfigType.generic).get(Config.newLineAfterParams, false); + this.newLineAfterTParams = workspace.getConfiguration(ConfigType.generic).get(Config.newLineAfterTParams, false); + this.briefTemplate = workspace.getConfiguration(ConfigType.generic).get(Config.briefTemplate, ""); + this.paramTemplate = workspace.getConfiguration(ConfigType.generic).get(Config.paramTemplate, ""); + this.tparamTemplate = workspace.getConfiguration(ConfigType.generic).get(Config.tparamTemplate, ""); + this.returnTemplate = workspace.getConfiguration(ConfigType.generic).get(Config.returnTemplate, ""); } - protected indentLine(commentLine: string): string { + protected getIndentation(): string { const line: TextLine = this.activeEditor.document.lineAt(this.activeEditor.selection.start.line); const lineTxt: string = line.text; let stringToIndent: string = ""; @@ -72,85 +82,75 @@ export default class CGen implements IDocGen { stringToIndent = stringToIndent + " "; } } - const textToInsert = stringToIndent + commentLine; - return textToInsert; + return stringToIndent; } - protected generateBrief() { - let line: string = ""; - line += this.lineStart; - line += this.commandIndicator; - line += DoxygenCommands.brief; - line += this.spaceAfterCommand; - this.comment += this.indentLine(line); + protected getTemplatedString(template: string, param: string): string { + return template.replace(this.templateReplaceString, param); } - protected generateDetailed() { - let line: string = ""; - line += this.lineStart; - line += "\n"; - this.comment += this.indentLine(line); - line = this.lineStart; - line += DoxygenCommands.detailed + "\n"; - this.comment += this.indentLine(line); - line = this.lineStart; - this.comment += this.indentLine(line); + protected generateBrief(lines: string[]) { + lines.push(this.commentPrefix + this.briefTemplate); } - protected generateParams() { + protected generateFromTemplate(lines: string[], template: string, templateWith: string[]) { let line: string = ""; - this.params.forEach((element: string) => { - line = this.lineStart; - line += this.commandIndicator; - line += DoxygenCommands.param + " "; // TODO: Make this customizable - line += element + "\n"; - this.comment += this.indentLine(line); + templateWith.forEach((element: string) => { + line = this.commentPrefix; + line += this.getTemplatedString(template, element); + lines.push(line); }); } - protected generateReturn() { - if (this.retVals.length === 0) { - return; + protected generateComment(): string { + let lines: string[] = []; + + if (this.firstLine.trim().length !== 0) { + lines.push(this.firstLine); } - let line: string = ""; - - if (this.params.length !== 0) { - line = this.lineStart + "\n"; - this.comment += this.indentLine(line); + + if (this.briefTemplate.trim().length !== 0) { + this.generateBrief(lines); + if (this.newLineAfterBrief === true) { + lines.push(this.commentPrefix); + } } - this.retVals.forEach((element: string) => { - line = this.lineStart; - line += this.commandIndicator; - line += DoxygenCommands.return + " "; // TODO: Make this customizable - line += element.trim() + "\n"; - this.comment += this.indentLine(line); - }); - } + if (this.tparamTemplate.trim().length !== 0 && this.tparams.length > 0) { + this.generateFromTemplate(lines, this.tparamTemplate, this.tparams); + if (this.newLineAfterTParams === true) { + lines.push(this.commentPrefix); + } + } - protected generateEnd() { - let line: string = " "; // TODO: Make this customizable - line += this.endComment; - this.comment += this.indentLine(line); - } + if (this.paramTemplate.trim().length !== 0 && this.params.length > 0) { + this.generateFromTemplate(lines, this.paramTemplate, this.params); + if (this.newLineAfterParams === true) { + lines.push(this.commentPrefix); + } + } - protected generateComment() { - this.generateBrief(); - this.comment += "\n"; - this.generateDetailed(); - this.comment += "\n"; - if (this.params.length !== 0) { // Only if we have parameters - this.generateParams(); + if (this.returnTemplate.trim().length !== 0 && this.retVals.length > 0) { + this.generateFromTemplate(lines, this.returnTemplate, this.retVals); } - if (this.retVals.length !== 0) { // Only if we have return values - this.generateReturn(); + + if (this.lastLine.trim().length !== 0) { + lines.push(this.lastLine); } - this.generateEnd(); + + const comment: string = lines.join("\n" + this.getIndentation()); + return comment; } - protected setCursor(line: number, character: number) { - const indentLen: number = this.indentLine("").length; + protected setCursorToBrief(line: number, character: number) { + // If there was a first line defined the brief is on the next line. + if (this.firstLine.trim().length !== 0) { + line++; + } + + character += this.commentPrefix.length + this.briefTemplate.length; + const move: Selection = new Selection(line, character, line, character); this.activeEditor.selection = move; } diff --git a/src/DocGen/DocGen.ts b/src/DocGen/DocGen.ts index 9de9d41..40ea205 100644 --- a/src/DocGen/DocGen.ts +++ b/src/DocGen/DocGen.ts @@ -1,19 +1,10 @@ -/** - * Contains the supported doxygen commands - * - * @export - * @enum {number} - */ -export enum DoxygenCommands { - brief = "brief", - return = "return", - param = "param", - detailed = "(Detailed description)", -} +import { Range } from "vscode"; + export interface IDocGen { /** - * Generate documentation string and write it to the active editor + * @brief Generate documentation string and write it to the active editor + * @param {Range} rangeToReplace Range to replace with the generated comment. */ - GenerateDoc(); + GenerateDoc(rangeToReplace: Range); } -- cgit v1.2.3