Updated various comments - Javadoc, method-level, intra-method.

src/io/nayuki/fastqrcodegen/QrCode.java

@@ -73,12 +73,12 @@ public final class QrCode {
 		assert dataUsedBits != -1;
 		
 		// Increase the error correction level while the data still fits in the current version number
-		for (Ecc newEcl : Ecc.values()) {
+		for (Ecc newEcl : Ecc.values()) {  // From low to high
 			if (boostEcl && dataUsedBits <= getNumDataCodewords(version, newEcl) * 8)
 				ecl = newEcl;
 		}
 		
-		// Create the data bit string by concatenating all segments
+		// Concatenate all segments to create the data bit string
 		int dataCapacityBits = getNumDataCodewords(version, ecl) * 8;
 		BitBuffer bb = new BitBuffer();
 		for (QrSegment seg : segs) {
@@ -91,7 +91,7 @@ public final class QrCode {
 		bb.appendBits(0, Math.min(4, dataCapacityBits - bb.bitLength));
 		bb.appendBits(0, (8 - bb.bitLength % 8) % 8);
 		
-		// Pad with alternate bytes until data capacity is reached
+		// Pad with alternating bytes until data capacity is reached
 		for (int padByte = 0xEC; bb.bitLength < dataCapacityBits; padByte ^= 0xEC ^ 0x11)
 			bb.appendBits(padByte, 8);
 		assert bb.bitLength % 8 == 0;
@@ -174,7 +174,8 @@ public final class QrCode {
 	 * @param scale the module scale factor, which must be positive
 	 * @param border the number of border modules to add, which must be non-negative
 	 * @return an image representing this QR Code, with padding and scaling
-	 * @throws IllegalArgumentException if the scale or border is out of range
+	 * @throws IllegalArgumentException if the scale or border is out of range, or if
+	 * {scale, border, size} cause the image dimensions to exceed Integer.MAX_VALUE
 	 */
 	public BufferedImage toImage(int scale, int border) {
 		if (scale <= 0 || border < 0)
@@ -199,6 +200,7 @@ public final class QrCode {
 	 * Note that Unix newlines (\n) are always used, regardless of the platform.
 	 * @param border the number of border modules to add, which must be non-negative
 	 * @return a string representing this QR Code as an SVG document
+	 * @throws IllegalArgumentException if the border is negative
 	 */
 	public String toSvgString(int border) {
 		if (border < 0)
@@ -325,10 +327,11 @@ public final class QrCode {
 	}
 	
 	
-	// XORs the data modules in this QR Code with the given mask pattern. Due to XOR's mathematical
-	// properties, calling applyMask(m) twice with the same value is equivalent to no change at all.
-	// This means it is possible to apply a mask, undo it, and try another mask. Note that a final
-	// well-formed QR Code symbol needs exactly one mask applied (not zero, not two, etc.).
+	// XORs the codeword modules in this QR Code with the given mask pattern.
+	// The function modules must be marked and the codeword bits must be drawn
+	// before masking. Due to the arithmetic of XOR, calling applyMask() with
+	// the same mask value a second time will undo the mask. A final well-formed
+	// QR Code symbol needs exactly one (not zero, two, etc.) mask applied.
 	private void applyMask(int[] mask) {
 		if (mask.length != modules.length)
 			throw new IllegalArgumentException();

src/io/nayuki/fastqrcodegen/QrTemplate.java

@@ -159,7 +159,7 @@ final class QrTemplate {
 	
 	
 	// Draws two copies of the version bits (with its own error correction code),
-	// based on this object's version field (which only has an effect for 7 <= version <= 40).
+	// based on this object's version field, iff 7 <= version <= 40.
 	private void drawVersion() {
 		if (version < 7)
 			return;
@@ -182,7 +182,8 @@ final class QrTemplate {
 	}
 	
 	
-	// Draws a 9*9 finder pattern including the border separator, with the center module at (x, y).
+	// Draws a 9*9 finder pattern including the border separator,
+	// with the center module at (x, y). Modules can be out of bounds.
 	private void drawFinderPattern(int x, int y) {
 		for (int i = -4; i <= 4; i++) {
 			for (int j = -4; j <= 4; j++) {
@@ -195,7 +196,8 @@ final class QrTemplate {
 	}
 	
 	
-	// Draws a 5*5 alignment pattern, with the center module at (x, y).
+	// Draws a 5*5 alignment pattern, with the center module
+	// at (x, y). All modules must be in bounds.
 	private void drawAlignmentPattern(int x, int y) {
 		for (int i = -2; i <= 2; i++) {
 			for (int j = -2; j <= 2; j++)
@@ -306,7 +308,7 @@ final class QrTemplate {
 			int numAlign = ver / 7 + 2;
 			result -= (25 * numAlign - 10) * numAlign - 55;
 			if (ver >= 7)
-				result -= 18 * 2;  // Subtract version information
+				result -= 18 * 2;
 		}
 		return result;
 	}