add comments; code style

Author: Xiaoji Chen

lib/index.js

@@ -404,7 +404,7 @@ GLSL.prototype.transforms = {
 		var inArgs = []
 		var outArgs = []
 		args.components.forEach(function (arg, index) {
-			arg.index = index;
+			arg.index = index
 			if (arg.qualifier.slice(0, 2) === 'in') {
 				inArgs.push(arg)
 			}
@@ -413,7 +413,7 @@ GLSL.prototype.transforms = {
 			}
 		})
 		if (outArgs.length === 0) {
-			outArgs = null;
+			outArgs = null
 		}
 
 		//if main name is registered - provide type-scoped name of function
@@ -427,20 +427,24 @@ GLSL.prototype.transforms = {
 		//create function body
 		result += `function ${name} (${args}) {\n`
 
-		//input parameters are copied
+		//guard input parameters from being mutated
 		inArgs.forEach(function (arg) {
 			if (/^(vec|mat)/.test(arg.type)) {
 				result += `${arg} = ${arg}.slice();\n`
 			}
 		})
 
-		var scope = this.scopes[this.currentScope];
-		scope.callName = name;
-		scope.outArgs = outArgs;
+		//populate current scope information
+		//this is used by the `return` transform
+		var scope = this.scopes[this.currentScope]
+		scope.callName = name
+		scope.outArgs = outArgs
 
 		result += this.process(node.children[2])
 
 		if (outArgs && outType === 'void') {
+			//the output list is usually created when transforming the `return` statement
+			//but this function does not have a `return` at the end
 			result += `\n${name}.__out__ = [${outArgs.join(', ')}];`
 		}
 
@@ -456,7 +460,9 @@ GLSL.prototype.transforms = {
 			complexity: 999
 		})
 
-		result.outArgs = outArgs;
+		//save the output arguments list
+		//this is used by the `call` transform
+		result.outArgs = outArgs
 
 		//register function descriptor
 		this.functions[name] = result
@@ -516,6 +522,7 @@ GLSL.prototype.transforms = {
 		if (node.parent.type === 'functionargs') {
 			result = this.process(decllist)
 
+			// in/out/inout
 			var qualifier = node.token.data
 			if (qualifier === result.type) {
 				result.qualifier = 'in'
@@ -766,18 +773,24 @@ GLSL.prototype.transforms = {
 
 	return: function (node) {
 		var expr = this.process(node.children[0])
-		var result;
-		var scope = this.scopes[this.currentScope];
+		var result
+		var scope = this.scopes[this.currentScope]
 		if (scope.outArgs) {
 			var outStmt = `${scope.callName}.__out__ = [${scope.outArgs.join(', ')}]`
 
 			if (expr.visible) {
+				// func.__return__ = <expression>;
+				// func.__out__ = [outArg1, outArg2, ...];
+				// return func.__return__;
 				result = `${scope.callName}.__return__ = ${expr};\n${outStmt};\nreturn ${scope.callName}.__return__`
 			} else {
+				// func.__out__ = [outArg1, outArg2, ...];
+				// return;
 				result = `${outStmt};\nreturn`
 			}
 		} else {
-			result = 'return' + (expr.visible ? ' ' + expr : '');
+			// return <expression>;
+			result = 'return' + (expr.visible ? ' ' + expr : '')
 		}
 		return Descriptor(result, {type: expr.type})
 	},
@@ -1165,11 +1178,13 @@ GLSL.prototype.transforms = {
 					optimize = false
 				}
 
-				var res = `${callName}(${argValues.join(', ')})`;
+				var res = `${callName}(${argValues.join(', ')})`
 				if (outArgs) {
+					// calling func(in a, out b, out c):
+					// (func(a, b, c), [b, c] = func.__out__, func.__return__)
 					var outList = outArgs.map(function (arg) {
 						return argValues[arg.index]
-					});
+					})
 					res = `(${res}, [${outList.join(', ')}] = ${callName}.__out__, ${callName}.__return__)`
 				}