first version commit for Solidity changes

Author: ngurmen

.vscode/tasks.json

@@ -8,23 +8,34 @@
 
 // A task runner that calls a custom npm script that compiles the extension.
 {
-	"version": "0.1.0",
+	"version": "2.0.0",
 
 	// we want to run npm
 	"command": "npm",
 
-	// the command is a shell script
-	"isShellCommand": true,
-
-	// show the output window only if unrecognized errors occur.
-	"showOutput": "silent",
-
 	// we run the custom script "compile" as defined in package.json
 	"args": ["run", "compile"],
 
-	// The tsc compiler is started in watching mode
-	"isWatching": true,
+	// The tsc compiler is started in background mode
+	"isBackground": true,
 
 	// use the standard tsc in watch mode problem matcher to find compile problems in the output.
-	"problemMatcher": "$tsc-watch"
-}
+	"problemMatcher": "$tsc-watch",
+	"tasks": [
+		{
+			"label": "npm",
+			"type": "shell",
+			"command": "npm",
+			"args": [
+				"run",
+				"compile"
+			],
+			"isBackground": true,
+			"problemMatcher": "$tsc-watch",
+			"group": {
+				"_id": "build",
+				"isDefault": false
+			}
+		}
+	]
+}

README.md

@@ -1,20 +1,21 @@
-# vscode-comment
-Adds simple jsdoc comments for the parameters of a selected function signature
+# VS Code Solidity Comments extension
+Adds NatSpec compliant @notice, @dev, @param and @return tags for function and modifier signatures in Solidity files.
 
-## 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.)
-
-![install and work](images/addDocComments.gif)
+## Installation
+Currently, the solidity-comments VS Code extension is installed from a VSIX file only.
 
+Go to `Extensions` tab and click the `...` at the top.
 
-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.
+Select `Install from VSIX`.
 
-## Limitations
-The extension does not support any other type of jsdoc tags. It only calculates @param and @return
+## Using
+In a Solidity file, move the cursor to a line with a function or modifier signature.
 
-Parameter types are not inferred based on usage. If a type is not specified, empty braces {} are returned.
+Invoke the `Add Solidity Comments` extension
+- Open the command palette wit `F1` or `ctrl+shift+p` on Windows and find `Add Solidity Comments`. Hit enter.
+- Alternatively, you can use the keybindings `ctrl+alt+d` on Windows and `shift+cmd+d` on Mac.
 
-## Other extensions
-[Document This](https://marketplace.visualstudio.com/items?itemName=joelday.docthis) provides the same functionality but supports many more tags
+The extension will parse the signature on the line of the cursor. A stub with @notice, @dev, @param and @return tags for each parameter and return variables will be added directly above the line.
 
-This project has adopted the [Microsoft Open Source Code of Conduct](https://opensource.microsoft.com/codeofconduct/). For more information see the [Code of Conduct FAQ](https://opensource.microsoft.com/codeofconduct/faq/) or contact [opencode@microsoft.com](mailto:opencode@microsoft.com) with any additional questions or comments.
+## Limitations
+The extension does not support any other type of NatSpec tags. It only uses @notice, @dev, @param and @return

argParser.ts

@@ -0,0 +1,187 @@
+
+export class paramDef {
+	constructor(public paramName: string, public paramType: string) {
+		this.paramName = paramName;
+		this.paramType = paramType;
+	}
+}
+
+export function getParameterText(functionParams: paramDef[], returnParams: paramDef[]): string {
+	var textToInsert: string = "";
+	textToInsert = textToInsert + '/**\n * @notice  .\n * @dev     .\n';
+	functionParams.forEach(element => {
+		if (element.paramName != '') {
+			textToInsert = textToInsert + ' * @param   ';
+			// textToInsert = textToInsert + '{' + element.paramType + '}' + ' ';  // for type insertion
+			textToInsert = textToInsert + element.paramName + '  .' + '\n';
+		}
+	});
+	returnParams.forEach(element => {
+		if (element.paramType != '') {
+			textToInsert = textToInsert + ' * @return  ';
+			// textToInsert = textToInsert + '{' + element.paramType + '}' + ' ';  // for type insertion
+			if (element.paramName != '') {
+				textToInsert = textToInsert + element.paramName + '  .' + '\n';
+			} else {
+				// textToInsert = textToInsert + 'UNNAMED' + '\n';                 // for type insertion
+				textToInsert = textToInsert + element.paramType + '  .' + '\n';
+			}
+		}
+	});
+	textToInsert = textToInsert + ' */';
+	return textToInsert;
+}
+
+// split a given line by a keyword
+// for Solidity keyword is expected to be used with 'returns'
+// everything before 'returns' will be used to build lines[0] for function parameters
+// everything after 'returns' will be used to build lines[1] for the return parameters
+export function splitTextByKeyword(text: string, keyword: string): string[] {
+	const result = text.trim().split(/\s+/);
+	const index = result.indexOf("{", 0);
+	if (index > -1) {
+		result.splice(index, 1);
+	}
+	let lines: string[] = [];
+	const rPos = result.indexOf(keyword);
+	if (rPos != -1) {
+		lines[0] = result.slice(0, rPos).join(" ");
+		lines[1] = result.slice(rPos + 1, result.length).join(" ");
+	} else {
+		lines[0] = result.slice(0, result.length).join(" ");
+		lines[1] = "";
+	}
+	return lines;
+}
+
+//Assumes that the string passed in starts with ( and continues to ) and does not contain any comments
+export function getFunctionParams(text: string): paramDef[] {
+	var params: paramDef[] = [];
+	//Start by looking for the function name declaration
+	var index = 0;
+	text = text.trim(); // delete the leading and trailing spaces
+	//if there is no '(' 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
+		var numBraces = 1;
+		index++;
+		while ((numBraces != 0) && (index != text.length)) {
+			var name_type: string = '';
+			while ((text.charAt(index) != ',') && (text.charAt(index) != ')') && (index < text.length)) {
+				name_type = name_type + text.charAt(index);
+				index++;
+			}
+			if (text.charAt(index) == ')') {
+				numBraces--;
+			}
+			name_type = name_type.trim() // trim leading and trailing whitespace
+			let parts = name_type.split(" ");  // spitting a returns element (bool b, uint256 u, ...)
+			let idx = parts.indexOf("memory", 0);  // remove memory from parts
+			if (idx > -1) {
+				parts.splice(idx, 1);
+			}
+			idx = parts.indexOf("calldata", 0);    // remove calldata from parts
+			if (idx > -1) {
+				parts.splice(idx, 1);
+			}
+			idx = parts.indexOf("storage", 0);     // remove storage from parts
+			if (idx > -1) {
+				parts.splice(idx, 1);
+			}
+			if (parts.length == 1) {
+				params.push(new paramDef("", ""));
+			} else if (parts.length == 2) {
+				params.push(new paramDef(parts[1], parts[0]));
+			} else {
+				const errorMessage = "Arguments are malformed in the selected code";
+				throw new Error(errorMessage);
+			}
+			if (index < text.length) {
+				index++;
+				while (text.charAt(index) == ' ') index++;  // consume whitespace
+			}
+		}
+	}
+	return params;
+}
+
+//Assumes that the string passed in starts with ( and continues to ) and does not contain any comments
+export function getReturnParams(text: string): paramDef[] {
+	var params: paramDef[] = [];
+	//Start by looking for the function name declaration
+	var index = 0;
+	text = text.trim(); // delete the leading and trailing spaces
+	//if there is no '(' 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
+		var numBraces = 1;
+		index++;
+		while ((numBraces != 0) && (index != text.length)) {
+			var name_type: string = '';
+			while ((text.charAt(index) != ',') && (text.charAt(index) != ')') && (index < text.length)) {
+				name_type = name_type + text.charAt(index);
+				index++;
+			}
+			if (text.charAt(index) == ')') {
+				numBraces--;
+			}
+			name_type = name_type.trim() // trim leading and trailing whitespace
+			const parts = name_type.split(" ");  // spitting a returns element (bool b, uint256 u, ...) or (bool, uint256, ...)
+			let idx = parts.indexOf("memory", 0);  // remove memory from parts
+			if (idx > -1) {
+				parts.splice(idx, 1);
+			}
+			idx = parts.indexOf("calldata", 0);    // remove calldata from parts
+			if (idx > -1) {
+				parts.splice(idx, 1);
+			}
+			idx = parts.indexOf("storage", 0);     // remove storage from parts
+			if (idx > -1) {
+				parts.splice(idx, 1);
+			}
+			if (parts.length == 0) {
+				params.push(new paramDef("", ""));
+			} else if (parts.length == 2) {
+				params.push(new paramDef(parts[1], parts[0]));
+			} else if (parts.length == 1) {
+				params.push(new paramDef("", parts[0]));
+			} else {
+				const errorMessage = "Elements of returns are malformed in the selected code";
+				throw new Error(errorMessage);
+			}
+			if (index < text.length) {
+				index++;
+				while (text.charAt(index) == ' ') index++;  // consume whitespace
+			}
+		}
+	}
+	return params;
+}
+
+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
+				index = index + 2;
+				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)) {
+				index++;
+			}
+		}
+		else {
+			uncommentedText = uncommentedText + text.charAt(index);
+			index++;
+		}
+	}
+	return uncommentedText;
+}