[doc] Improve doc comments for lib/util

lib/util/Arrays.v3

@@ -3,66 +3,66 @@
 
 // Utility methods for arrays.
 component Arrays {
-	// get the length of {array}, but returning 0 for a null array
+	// Get the length of {array}, returning {0} for a null array.
 	def length<T>(array: Array<T>) -> int {
 		return if(array == null, 0, array.length);
 	}
-	// compute a hash of {array}, given a {hash} function for each element
+	// Compute a hash of {array}, given a {hash} function for each element.
 	def hash<T>(h0: int, array: Array<T>, hash: T -> int) -> int {
 		for (e in array) h0 = h0 * 33 + hash(e);
 		return h0;
 	}
-	// compare elements of {x} and {y} for equality
+	// Compare elements of {x} and {y} for equality.
 	def equal<A>(x: Array<A>, y: Array<A>) -> bool {
 		if (x == y) return true;
 		if (x.length != y.length) return false;
 		for (i < x.length) if (x[i] != y[i]) return false;
 		return true;
 	}
-	// map {func} over an input {array}, returning a new array of the results
+	// Map {func} over an input {array}, returning a new array of the results.
 	def map<A, B>(array: Array<A>, func: A -> B) -> Array<B> {
 		if (array == null) return null;
 		var max = array.length, r = Array<B>.new(max);
 		for (i < max) r[i] = func(array[i]);
 		return r;
 	}
-	// map {func} over an input {array}, storing the results in the {dest}
+	// Map {func} over an input {array}, storing the results in the {dest}.
 	def mapInto<A, B>(array: Array<A>, func: A -> B, dest: Array<B>) {
 		if (array == null) return;
 		for (i < array.length) dest[i] = func(array[i]);
 	}
-	// make a copy of a {src} array
+	// Make a copy of a {src} array.
 	def dup<T>(src: Array<T>) -> Array<T>{
 		var max = src.length, dst = Array<T>.new(max);
 		for (i < max) dst[i] = src[i];
 		return dst;
 	}
-	// make a copy of {array} and replace {array[index]} with {val}
+	// Make a copy of {array} and replace {array[index]} with {val}.
 	def replace<T>(array: Array<T>, index: int, val: T) -> Array<T> {
 		array = dup(array);
 		array[index] = val;
 		return array;
 	}
-	// delete the element at {index} in {array}
+	// Delete the element at {index} in {array}.
 	def deleteAt<T>(array: Array<T>, index: int) -> Array<T> {
 		var n = Array<T>.new(array.length - 1);
 		for (i < index) n[i] = array[i];
 		for (i = index + 1; i < array.length; i++) n[i - 1] = array[i];
 		return n;
 	}
-	// copy elements from {src} into {dst}, up to {dst.length}
+	// Copy elements from {src} into {dst}, up to {dst.length}.
 	def copy<T>(src: Array<T>, dst: Array<T>) -> Array<T>{
 		var max = src.length;
 		if (max > dst.length) max = dst.length;
 		for (i < max) dst[i] = src[i];
 		return dst;
 	}
-	// copy elements from {src} into {dst}, starting at destination index {destIndex}
+	// Copy elements from {src} into {dst}, starting at destination index {destIndex}.
 	def copyInto<T>(src: Array<T>, dst: Array<T>, destIndex: int) {
 		var max = src.length;
 		for (i < max) dst[i + destIndex] = src[i];
 	}
-	// concatentate arrays {a} and {b} into a new array
+	// Concatentate arrays {a} and {b} into a new array.
 	def concat<T>(a: Array<T>, b: Array<T>) -> Array<T> {
 		var amax = a.length;
 		var r = Array<T>.new(amax + b.length);
@@ -71,7 +71,7 @@ component Arrays {
 		for (i < bmax) r[i + amax] = b[i];
 		return r;
 	}
-	// grow an {array} if it is smaller than size, returning either {array} or a new one
+	// Grow an {array} if it is smaller than {size}, returning either {array} or a new one.
 	def grow<T>(array: Array<T>, size: int) -> Array<T> {
 		if (size > array.length) {
 			var n = Array<T>.new(size), max = array.length;
@@ -80,15 +80,15 @@ component Arrays {
 		}
 		return array;
 	}
-	// grow an {array} if its smaller than {nlength}, using the specified
-	// {val} for new elements.
+	// Grow an {array} if its smaller than {nlength}, using the specified {val} for new
+	// elements.
 	def growV<T>(array: Array<T>, nlength: int, val: T) -> Array<T> {
 		var narray = Array<T>.new(nlength);
 		for (i < array.length) narray[i] = array[i];
 		for (i = array.length; i < narray.length; i++) narray[i] = val;
 		return narray;
 	}
-	// prepend a single {val} to an {array}, returning a new array
+	// Prepend a single {val} to an {array}, returning a new array.
 	def prepend<T>(val: T, array: Array<T>) -> Array<T> {
 		var max = array.length;
 		if (array == null || max == 0) return [val];
@@ -97,40 +97,40 @@ component Arrays {
 		for (i < max) narray[i + 1] = array[i];
 		return narray;
 	}
-	// append a single {val} to an {array}, returning a new array
+	// Append a single {val} to an {array}, returning a new array.
 	def append<T>(val: T, array: Array<T>) -> Array<T> {
 		var result = grow(array, array.length + 1);
 		result[array.length] = val;
 		return result;
 	}
-	// make a copy of a range of an {array}, from {start} inclusive to {end} exclusive
+	// Make a copy of a range of an {array}, from {start} inclusive to {end} exclusive.
 	def range<T>(array: Array<T>, start: int, end: int) -> Array<T> {
 		var n = Array<T>.new(end - start);
 		for (i = start; i < end; i++) n[i - start] = array[i];
 		return n;
 	}
-	// remove the element from {array} at {index} and slide elements down
+	// Remove the element from {array} at {index} and slide elements down.
 	def removeIndex<T>(array: Array<T>, index: int) {
 		for (i = index + 1; i < array.length; i++) {
 			array[i - 1] = array[i];
 		}
 	}
-	// return {true} if for all {i}, {cond(arr1[i], arr2[i])}
+	// Return {true} if for all {i}, {cond(arr1[i], arr2[i])}.
 	def allTrue<T>(x: Array<T>, y: Array<T>, cond: (T, T) -> bool) -> bool {
 		if (x.length != y.length) return false;
 		for (i < x.length) if (!cond(x[i], y[i])) return false;
 		return true;
 	}
-	// return {true} if for any {i}, {cond(arr1[i], arr2[i])}
+	// Return {true} if for any {i}, {cond(arr1[i], arr2[i])}.
 	def anyTrue<T>(x: Array<T>, y: Array<T>, cond: (T, T) -> bool) -> bool {
 		for (i < x.length) {
 			if (i >= y.length) return false;
 			if (cond(x[i], y[i])) return true;
 		}
 		return false;
 	}
-	// perform mergesort on {array} for elements between {start} inclusive and {end} exclusive,
-	// using the {cmp} function
+	// Perform mergesort on {array} for elements between {start} inclusive and {end} exclusive,
+	// using the {cmp} function.
 	def sort<T>(array: Array<T>, start: int, end: int, cmp: (T, T) -> bool) -> Array<T> {
 		var size = end - start;
 		if (size == 0) return [];
@@ -161,7 +161,7 @@ component Arrays {
 		}
 		return array;
 	}
-	// helper for merge sort routine
+	// Helper for merge sort routine.
 	private def finish<T>(array: Array<T>, k: int, end: Array<T>, i: int) -> Array<T> {
 		while (k < array.length) array[k++] = end[i++];
 		return array;

lib/util/Chars.v3

@@ -7,8 +7,7 @@ component Chars {
 	def hexMap_u = "0123456789ABCDEF";
 	def hexMap_l = "0123456789abcdef";
 
-	// Return the hexadecimal value of the character; -1 if not a valid
-	// hexadecimal character.
+	// Return the hexadecimal value of the character; -1 if not a valid hexadecimal character.
 	def hexValue(ch: byte) -> int {
 		if (ch < '0')  return -1;
 		if (ch <= '9') return int.!(ch) - '0';
@@ -18,21 +17,21 @@ component Chars {
 		if (ch <= 'f') return 10 + int.!(ch) - 'a';
 		return -1;
 	}
-	// checks if {ch} is an ASCII base-10 digit
+	// Check if {ch} is an ASCII base-10 digit.
 	def isDecimal(ch: byte) -> bool {
 		return (u32.view(ch) - '0') <= 9;
 	}
-	// checks if {ch} is an ASCII base-16 digit
+	// Check if {ch} is an ASCII base-16 digit.
 	def isHex(ch: byte) -> bool {
 		var u = u32.view(ch);
 		return ((u - '0') <= 9) || ((u - 'a') <= 5) || ((u - 'A') <= 5);
 	}
-	// checks if {ch} is an ASCII binary digit
+	// Checks if {ch} is an ASCII binary digit.
 	def isBinary(ch: byte) -> bool {
 		return (u32.view(ch) - '0') <= 1;
 	}
-	// Parse a (single-quoted) literal at the given position in the array,
-	// returning a pair of status (# success characters if > 0) and the value.
+	// Parse a (single-quoted) literal at the given position in the array, returning a pair of
+	// status (# success characters if > 0) and the value.
 	def parseLiteral(a: Array<byte>, pos: int) -> (int, byte) {
 		if (pos + 2 >= a.length) return (0, 0);
 		if (a[pos] != '\'') return (0, 0);
@@ -51,7 +50,7 @@ component Chars {
 		if (a[end] == '\'') return (1 + end - pos, ch);
 		return (0 - (1 + end - pos), 0);
 	}
-	// parses an escaped byte such as \n, \r, \t, \\, \xXX starting at {a(pos)}
+	// Parse an escaped byte such as \n, \r, \t, \\, \xXX starting at {a(pos)}.
 	def parseEscape(a: Array<byte>, pos: int) -> (int, byte) {
 		if (pos >= a.length) return (0, 0);
 		match (a[pos]) {