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. --- src/CodeParser/CParser.ts | 19 ++-- src/CodeParser/CodeParserController.ts | 31 +++--- src/Config.ts | 13 ++- src/DocGen/CGen.ts | 172 ++++++++++++++++----------------- src/DocGen/DocGen.ts | 19 +--- 5 files changed, 128 insertions(+), 126 deletions(-) (limited to 'src') 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