diff --git a/README.md b/README.md index 5f6fece..ef6af66 100644 --- a/README.md +++ b/README.md @@ -1,8 +1,8 @@ # vscode-comment -Adds simple jsdoc comments for the parameters of a selected function signature +Adds simple JSDoc comments for the parameters of a selected function signature. ## Using -In a typescript or javascript file, select a function signature, ideally one that contains one or more parameters. Select the whole function signature then invoke the Add Doc Comments extension (open the command palette (F1 on Windows) and look for the command 'Add doc comments'. Hit enter.) +In a TypeScript or JavaScript file, select a function signature, ideally one that contains one or more parameters. Select the whole function signature then invoke the Add Doc Comments extension (open the command palette (F1 on Windows) and look for the command 'Add doc comments'. Hit enter.) ![install and work](images/addDocComments.gif) @@ -10,7 +10,7 @@ In a typescript or javascript file, select a function signature, ideally one th The extension will parse the selected signature and add @param and @return tags for each parameter and any return type in the selected signature, directly above the signature. ## Limitations -The extension does not support any other type of jsdoc tags. It only calculates @param and @return +The extension does not support any other type of JSDoc tags. It only calculates @param and @return Parameter types are not inferred based on usage. If a type is not specified, empty braces {} are returned. diff --git a/extension.ts b/extension.ts index 653c301..6ca2aee 100644 --- a/extension.ts +++ b/extension.ts @@ -4,23 +4,18 @@ var indentString = require('indent-string'); import * as functionParser from './functionParser'; -export function activate(ctx:vscode.ExtensionContext) { +export function activate(ctx: vscode.ExtensionContext) { vscode.commands.registerCommand('extension.addDocComments', () => { var lang = vscode.window.activeTextEditor.document.languageId; - if ((lang == "typescript") || (lang == 'javascript')) { + if ((lang === "typescript") || (lang === 'javascript')) { var selection = vscode.window.activeTextEditor.selection; var startLine = selection.start.line - 1; var selectedText = vscode.window.activeTextEditor.document.getText(selection); - var outputMessage: string = 'Please select a TypeScript or JavaScript function signature' + var outputMessage: string = 'Please select a TypeScript or JavaScript function signature'; - if (selectedText.length === 0) { - vscode.window.showInformationMessage(outputMessage); - return; - } - - if (functionParser.stripComments(selectedText).length === 0) { + if (selectedText.length === 0 || functionParser.stripComments(selectedText).length === 0) { vscode.window.showInformationMessage(outputMessage); return; } @@ -53,35 +48,31 @@ export function activate(ctx:vscode.ExtensionContext) { } //Check if there is any text on startLine. If there is, add a new line at the end var lastCharIndex = vscode.window.activeTextEditor.document.lineAt(startLine).text.length; - var pos:vscode.Position; - if ((lastCharIndex > 0) && (startLine !=0)) { + var pos: vscode.Position; + if ((lastCharIndex > 0) && (startLine !== 0)) { pos = new vscode.Position(startLine, lastCharIndex); textToInsert = '\n' + textToInsert; } else { pos = new vscode.Position(startLine, 0); } - var line:string = vscode.window.activeTextEditor.document.lineAt(selection.start.line).text; - var firstNonWhiteSpace :number = vscode.window.activeTextEditor.document.lineAt(selection.start.line).firstNonWhitespaceCharacterIndex; - var numIndent : number = 0; - var tabSize : number = vscode.window.activeTextEditor.options.tabSize; + var line: string = vscode.window.activeTextEditor.document.lineAt(selection.start.line).text; + var firstNonWhiteSpace: number = vscode.window.activeTextEditor.document.lineAt(selection.start.line).firstNonWhitespaceCharacterIndex; var stringToIndent: string = ''; for (var i = 0; i < firstNonWhiteSpace; i++) { - if (line.charAt(i) == '\t') { + if (line.charAt(i) === '\t') { stringToIndent = stringToIndent + '\t'; } - else if (line.charAt(i) == ' ') { + else if (line.charAt(i) === ' ') { stringToIndent = stringToIndent + ' '; } } textToInsert = indentString(textToInsert, stringToIndent, 1); editBuilder.insert(pos, textToInsert); - }).then(() => { - + }).then(() => { + // Do nothing }); } } }); } - - diff --git a/functionParser.ts b/functionParser.ts index c6faddc..faefcce 100644 --- a/functionParser.ts +++ b/functionParser.ts @@ -6,27 +6,25 @@ export class paramDeclaration { } } - export function getParameterText(paramList: paramDeclaration[], returnText: string): string { - var textToInsert: string = ""; + var textToInsert: string = ''; textToInsert = textToInsert + '/**\n *'; paramList.forEach(element => { - if (element.paramName != '') { + if (element.paramName !== '') { textToInsert = textToInsert + ' @param '; - //if (element.paramType != '') { + //if (element.paramType !== '') { textToInsert = textToInsert + '{' + element.paramType + '}' + ' '; //} textToInsert = textToInsert + element.paramName + '\n' + ' *'; } }); - if (returnText != '') { + if (returnText !== '') { textToInsert = textToInsert + ' @returns ' + returnText + '\n' + ' *'; } textToInsert = textToInsert + '/'; return textToInsert; } - export function getReturns(text: string): string { var returnText: string = ''; text = text.replace(/\s/g, ''); @@ -34,8 +32,8 @@ export function getReturns(text: string): string { var lastIndex = text.lastIndexOf(':'); var lastBrace = text.lastIndexOf(')'); if (lastIndex > lastBrace) { - //we have a return type - //read to end of string + //We have a return type + //Read to end of string var index = lastIndex + 1; var splicedText = text.slice(index, text.length); returnText = splicedText.match(/[a-zA-Z][a-zA-Z0-9$_]*/).toString(); @@ -50,20 +48,20 @@ export function getReturns(text: string): string { export function stripComments(text: string): string { var uncommentedText: string = ''; var index = 0; - while (index != text.length) { - if ((text.charAt(index) == '/') && (text.charAt(index + 1) == '*')) { - //parse comment - if ((index + 2) != text.length) { //Check for the corner case that the selected text contains a /* right at the end + while (index !== text.length) { + if ((text.charAt(index) === '/') && (text.charAt(index + 1) === '*')) { + //Parse comment + if ((index + 2) !== text.length) { //Check for the corner case that the selected text contains a /* right at the end index = index + 2; - while ((text.charAt(index) != '*') && (text.charAt(index + 1) != '/')) { + while ((text.charAt(index) !== '*') && (text.charAt(index + 1) !== '/')) { index++; } } index = index + 2; } - else if ((text.charAt(index) == '/') && (text.charAt(index + 1) == '/')) { - //read to end of line - while ((text.charAt(index) != '\n') && (index < text.length)) { + else if ((text.charAt(index) === '/') && (text.charAt(index + 1) === '/')) { + //Read to end of line + while ((text.charAt(index) !== '\n') && (index < text.length)) { index++; } } @@ -75,7 +73,6 @@ export function stripComments(text: string): string { return uncommentedText; } - //Assumes that the string passed in starts with ( and continues to ) and does not contain any comments or white space export function getParameters(text: string): paramDeclaration[] { var paramList: paramDeclaration[] = []; @@ -84,36 +81,36 @@ export function getParameters(text: string): paramDeclaration[] { text = text.replace(/\s/g, ''); //Now we are at the first non whitespace character //if it is not a '(' then this is not a valid function declaration - if (text.charAt(index) == '(') { - //count the number of matching opening and closing braces. Keep parsing until 0 + if (text.charAt(index) === '(') { + //Count the number of matching opening and closing braces. Keep parsing until 0 var numBraces = 1; index++; - while ((numBraces != 0) && (index != text.length)) { + while ((numBraces !== 0) && (index !== text.length)) { //Now we are at a non whitespace character. Assume it is the parameter name var name: string = ''; - while ((text.charAt(index) != ':') && (text.charAt(index) != ',') && (text.charAt(index) != ')') && (index < text.length)) { + while ((text.charAt(index) !== ':') && (text.charAt(index) !== ',') && (text.charAt(index) !== ')') && (index < text.length)) { name = name + text.charAt(index); index++; } if (index < text.length) { //Now we are at a : or a ',', skip then read until a , to get the param type var type: string = ''; - if (text.charAt(index) == ':') { + if (text.charAt(index) === ':') { index++; - //we have a type to process - if (text.charAt(index) == '(') { + //We have a type to process + if (text.charAt(index) === '(') { var startNumBraces = numBraces; numBraces++; type = type + text.charAt(index); index++; - //we have encountered a function type - //read all the way through until the numBraces = startNumBraces - while ((numBraces != startNumBraces) && (index < text.length)) { - if (text.charAt(index) == ')') { + //We have encountered a function type + //Read all the way through until the numBraces = startNumBraces + while ((numBraces !== startNumBraces) && (index < text.length)) { + if (text.charAt(index) === ')') { numBraces--; } - else if (text.charAt(index) == '(') { + else if (text.charAt(index) === '(') { numBraces++; } type = type + text.charAt(index); @@ -121,27 +118,27 @@ export function getParameters(text: string): paramDeclaration[] { } if (index < text.length) { //Now read up to either a , or a ) - while ((text.charAt(index) != ',') && (text.charAt(index) != ')')) { + while ((text.charAt(index) !== ',') && (text.charAt(index) !== ')')) { type = type + text.charAt(index); index++; } - if (text.charAt(index) == ')') { + if (text.charAt(index) === ')') { numBraces--; } } } else { - while ((text.charAt(index) != ',') && (text.charAt(index) != ')') && (index != text.length)) { + while ((text.charAt(index) !== ',') && (text.charAt(index) !== ')') && (index !== text.length)) { type = type + text.charAt(index); index++; } - if (text.charAt(index) == ')') { + if (text.charAt(index) === ')') { numBraces--; } } } else { - //no type is specified + //No type is specified type = ''; } paramList.push(new paramDeclaration(name, type)); @@ -150,8 +147,7 @@ export function getParameters(text: string): paramDeclaration[] { } } } - } return paramList; -} \ No newline at end of file +} diff --git a/vsc-extension-quickstart.md b/vsc-extension-quickstart.md index b28b0b8..8115843 100644 --- a/vsc-extension-quickstart.md +++ b/vsc-extension-quickstart.md @@ -6,14 +6,14 @@ * extension.ts - this is the main file where you will provide the implementation of your command. The file exports one function, activate, which is called the very first time your extension is activated (in this case by executing the command). Inside the activate function we call registerCommand. We pass the function containing the implementation of the command as the second parameter to registerCommand ## Get up and running straight away -* press F5 to open a new window with your extension loaded -* run your command from the command palette by pressing F1 and typing 'Hello World' -* set breakpoints in your code inside extension.ts to debug your extension -* find output from your extension in the debug console +* Press F5 to open a new window with your extension loaded +* Run your command from the command palette by pressing F1 and typing 'Hello World' +* Set breakpoints in your code inside extension.ts to debug your extension +* Find output from your extension in the debug console ## Make changes -* you can relaunch the extension from the debug toolbar after changing code in extension.ts -* you can also reload (`Ctrl+R` or `Cmd+R` on Mac) the VS Code window with your extension to load your changes +* You can relaunch the extension from the debug toolbar after changing code in extension.ts +* You can also reload (`Ctrl+R` or `Cmd+R` on Mac) the VS Code window with your extension to load your changes ## Explore the API -* you can open the full set of our API when you open the file node_modules/vscode/vscode.d.ts \ No newline at end of file +* You can open the full set of our API when you open the file node_modules/vscode/vscode.d.ts \ No newline at end of file