Added and updated 4 comments in all language versions.

c/qrcodegen.c

@@ -456,7 +456,7 @@ static void drawFormatBits(enum qrcodegen_Ecc ecl, enum qrcodegen_Mask mask, uin
 		setModule(qrcode, qrsize - 1 - i, 8, getBit(data, i));
 	for (int i = 8; i < 15; i++)
 		setModule(qrcode, 8, qrsize - 15 + i, getBit(data, i));
-	setModule(qrcode, 8, qrsize - 8, true);
+	setModule(qrcode, 8, qrsize - 8, true);  // Always black
 }
 
 
@@ -519,10 +519,11 @@ static void drawCodewords(const uint8_t data[], int dataLen, uint8_t qrcode[]) {
 }
 
 
-// XORs the data modules in this QR Code with the given mask pattern. Due to XOR's mathematical
+// XORs the codeword modules in this QR Code with the given mask pattern.
-// properties, calling applyMask(..., m) twice with the same value is equivalent to no change at all.
+// The function modules must be marked and the codeword bits must be drawn
-// This means it is possible to apply a mask, undo it, and try another mask. Note that a final
+// before masking. Due to the arithmetic of XOR, calling applyMask() with
-// well-formed QR Code symbol needs exactly one mask applied (not zero, not two, etc.).
+// 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.
 static void applyMask(const uint8_t functionModules[], uint8_t qrcode[], enum qrcodegen_Mask mask) {
 	assert(0 <= (int)mask && (int)mask <= 7);  // Disallows qrcodegen_Mask_AUTO
 	int qrsize = qrcodegen_getSize(qrcode);
@@ -913,12 +914,12 @@ bool qrcodegen_encodeSegmentsAdvanced(const struct qrcodegen_Segment segs[], siz
 	assert(dataUsedBits != -1);
 	
 	// Increase the error correction level while the data still fits in the current version number
-	for (int i = (int)qrcodegen_Ecc_MEDIUM; i <= (int)qrcodegen_Ecc_HIGH; i++) {
+	for (int i = (int)qrcodegen_Ecc_MEDIUM; i <= (int)qrcodegen_Ecc_HIGH; i++) {  // From low to high
 		if (boostEcl && dataUsedBits <= getNumDataCodewords(version, (enum qrcodegen_Ecc)i) * 8)
 			ecl = (enum qrcodegen_Ecc)i;
 	}
 	
-	// Create the data bit string by concatenating all segments
+	// Concatenate all segments to create the data bit string
 	int dataCapacityBits = getNumDataCodewords(version, ecl) * 8;
 	memset(qrcode, 0, qrcodegen_BUFFER_LEN_FOR_VERSION(version) * sizeof(qrcode[0]));
 	int bitLen = 0;

cpp/QrCode.cpp

@@ -81,12 +81,12 @@ QrCode QrCode::encodeSegments(const vector<QrSegment> &segs, Ecc ecl,
 		throw std::logic_error("Assertion error");
 	
 	// Increase the error correction level while the data still fits in the current version number
-	for (Ecc newEcl : vector<Ecc>{Ecc::MEDIUM, Ecc::QUARTILE, Ecc::HIGH}) {
+	for (Ecc newEcl : vector<Ecc>{Ecc::MEDIUM, Ecc::QUARTILE, Ecc::HIGH}) {  // 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
 	size_t dataCapacityBits = getNumDataCodewords(version, ecl) * 8;
 	BitBuffer bb;
 	for (const QrSegment &seg : segs) {
@@ -241,7 +241,7 @@ void QrCode::drawFormatBits(int mask) {
 		setFunctionModule(size - 1 - i, 8, getBit(data, i));
 	for (int i = 8; i < 15; i++)
 		setFunctionModule(8, size - 15 + i, getBit(data, i));
-	setFunctionModule(8, size - 8, true);
+	setFunctionModule(8, size - 8, true);  // Always black
 }
 
 

cpp/QrCode.hpp

@@ -206,10 +206,11 @@ class QrCode final {
 	private: void drawCodewords(const std::vector<std::uint8_t> &data);
 	
 	
-	// XORs the data modules in this QR Code with the given mask pattern. Due to XOR's mathematical
+	// XORs the codeword modules in this QR Code with the given mask pattern.
-	// properties, calling applyMask(m) twice with the same value is equivalent to no change at all.
+	// The function modules must be marked and the codeword bits must be drawn
-	// This means it is possible to apply a mask, undo it, and try another mask. Note that a final
+	// before masking. Due to the arithmetic of XOR, calling applyMask() with
-	// well-formed QR Code symbol needs exactly one mask applied (not zero, not two, etc.).
+	// 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);
 	
 	

java/io/nayuki/qrcodegen/QrCode.java

@@ -131,12 +131,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) {
@@ -368,7 +368,7 @@ public final class QrCode {
 			setFunctionModule(size - 1 - i, 8, getBit(data, i));
 		for (int i = 8; i < 15; i++)
 			setFunctionModule(8, size - 15 + i, getBit(data, i));
-		setFunctionModule(8, size - 8, true);
+		setFunctionModule(8, size - 8, true);  // Always black
 	}
 	
 	
@@ -497,10 +497,11 @@ public final class QrCode {
 	}
 	
 	
-	// XORs the data modules in this QR Code with the given mask pattern. Due to XOR's mathematical
+	// XORs the codeword modules in this QR Code with the given mask pattern.
-	// properties, calling applyMask(m) twice with the same value is equivalent to no change at all.
+	// The function modules must be marked and the codeword bits must be drawn
-	// This means it is possible to apply a mask, undo it, and try another mask. Note that a final
+	// before masking. Due to the arithmetic of XOR, calling applyMask() with
-	// well-formed QR Code symbol needs exactly one mask applied (not zero, not two, etc.).
+	// 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 < 0 || mask > 7)
 			throw new IllegalArgumentException("Mask value out of range");

javascript/qrcodegen.js

@@ -245,7 +245,7 @@ var qrcodegen = new function() {
 				setFunctionModule(size - 1 - i, 8, getBit(data, i));
 			for (var i = 8; i < 15; i++)
 				setFunctionModule(8, size - 15 + i, getBit(data, i));
-			setFunctionModule(8, size - 8, true);
+			setFunctionModule(8, size - 8, true);  // Always black
 		}
 		
 		
@@ -377,10 +377,11 @@ var qrcodegen = new function() {
 		}
 		
 		
-		// XORs the data modules in this QR Code with the given mask pattern. Due to XOR's mathematical
+		// XORs the codeword modules in this QR Code with the given mask pattern.
-		// properties, calling applyMask(m) twice with the same value is equivalent to no change at all.
+		// The function modules must be marked and the codeword bits must be drawn
-		// This means it is possible to apply a mask, undo it, and try another mask. Note that a final
+		// before masking. Due to the arithmetic of XOR, calling applyMask() with
-		// well-formed QR Code symbol needs exactly one mask applied (not zero, not two, etc.).
+		// 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.
 		function applyMask(mask) {
 			if (mask < 0 || mask > 7)
 				throw "Mask value out of range";
@@ -545,12 +546,12 @@ var qrcodegen = new function() {
 		}
 		
 		// Increase the error correction level while the data still fits in the current version number
-		[this.Ecc.MEDIUM, this.Ecc.QUARTILE, this.Ecc.HIGH].forEach(function(newEcl) {
+		[this.Ecc.MEDIUM, this.Ecc.QUARTILE, this.Ecc.HIGH].forEach(function(newEcl) {  // From low to high
 			if (boostEcl && dataUsedBits <= QrCode.getNumDataCodewords(version, newEcl) * 8)
 				ecl = newEcl;
 		});
 		
-		// Create the data bit string by concatenating all segments
+		// Concatenate all segments to create the data bit string
 		var dataCapacityBits = QrCode.getNumDataCodewords(version, ecl) * 8;
 		var bb = new BitBuffer();
 		segs.forEach(function(seg) {

python/qrcodegen.py

@@ -111,11 +111,11 @@ class QrCode(object):
 			raise AssertionError()
 		
 		# Increase the error correction level while the data still fits in the current version number
-		for newecl in (QrCode.Ecc.MEDIUM, QrCode.Ecc.QUARTILE, QrCode.Ecc.HIGH):
+		for newecl in (QrCode.Ecc.MEDIUM, QrCode.Ecc.QUARTILE, QrCode.Ecc.HIGH):  # From low to high
 			if boostecl and datausedbits <= QrCode._get_num_data_codewords(version, newecl) * 8:
 				ecl = newecl
 		
-		# Create the data bit string by concatenating all segments
+		# Concatenate all segments to create the data bit string
 		datacapacitybits = QrCode._get_num_data_codewords(version, ecl) * 8
 		bb = _BitBuffer()
 		for seg in segs:
@@ -291,7 +291,7 @@ class QrCode(object):
 			self._set_function_module(self._size - 1 - i, 8, _get_bit(data, i))
 		for i in range(8, 15):
 			self._set_function_module(8, self._size - 15 + i, _get_bit(data, i))
-		self._set_function_module(8, self._size - 8, True)
+		self._set_function_module(8, self._size - 8, True)  # Always black
 	
 	
 	def _draw_version(self):
@@ -404,10 +404,11 @@ class QrCode(object):
 	
 	
 	def _apply_mask(self, mask):
-		"""XORs the data modules in this QR Code with the given mask pattern. Due to XOR's mathematical
+		"""XORs the codeword modules in this QR Code with the given mask pattern.
-		properties, calling applyMask(m) twice with the same value is equivalent to no change at all.
+		The function modules must be marked and the codeword bits must be drawn
-		This means it is possible to apply a mask, undo it, and try another mask. Note that a final
+		before masking. Due to the arithmetic of XOR, calling applyMask() with
-		well-formed QR Code symbol needs exactly one mask applied (not zero, not two, etc.)."""
+		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."""
 		if not (0 <= mask <= 7):
 			raise ValueError("Mask value out of range")
 		masker = QrCode._MASK_PATTERNS[mask]

rust/src/lib.rs

@@ -123,13 +123,13 @@ impl QrCode {
 		}
 		
 		// Increase the error correction level while the data still fits in the current version number
-		for newecl in &[QrCodeEcc::Medium, QrCodeEcc::Quartile, QrCodeEcc::High] {
+		for newecl in &[QrCodeEcc::Medium, QrCodeEcc::Quartile, QrCodeEcc::High] {  // From low to high
 			if boostecl && datausedbits <= QrCode::get_num_data_codewords(version, *newecl) * 8 {
 				ecl = *newecl;
 			}
 		}
 		
-		// Create the data bit string by concatenating all segments
+		// Concatenate all segments to create the data bit string
 		let datacapacitybits: usize = QrCode::get_num_data_codewords(version, ecl) * 8;
 		let mut bb = BitBuffer(Vec::new());
 		for seg in segs {
@@ -334,7 +334,7 @@ impl QrCode {
 		for i in 8 .. 15 {
 			self.set_function_module(8, size - 15 + i, get_bit(data, i));
 		}
-		self.set_function_module(8, size - 8, true);
+		self.set_function_module(8, size - 8, true);  // Always black
 	}
 	
 	
@@ -474,10 +474,11 @@ impl QrCode {
 	}
 	
 	
-	// XORs the data modules in this QR Code with the given mask pattern. Due to XOR's mathematical
+	// XORs the codeword modules in this QR Code with the given mask pattern.
-	// properties, calling applyMask(m) twice with the same value is equivalent to no change at all.
+	// The function modules must be marked and the codeword bits must be drawn
-	// This means it is possible to apply a mask, undo it, and try another mask. Note that a final
+	// before masking. Due to the arithmetic of XOR, calling applyMask() with
-	// well-formed QR Code symbol needs exactly one mask applied (not zero, not two, etc.).
+	// 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.
 	fn apply_mask(&mut self, mask: Mask) {
 		let mask: u8 = mask.value();
 		for y in 0 .. self.size {

typescript/qrcodegen.ts

@@ -95,12 +95,12 @@ namespace qrcodegen {
 			}
 			
 			// Increase the error correction level while the data still fits in the current version number
-			[QrCode_Ecc.MEDIUM, QrCode_Ecc.QUARTILE, QrCode_Ecc.HIGH].forEach((newEcl: QrCode_Ecc) => {
+			[QrCode_Ecc.MEDIUM, QrCode_Ecc.QUARTILE, QrCode_Ecc.HIGH].forEach((newEcl: QrCode_Ecc) => {  // From low to high
 				if (boostEcl && dataUsedBits <= QrCode.getNumDataCodewords(version, newEcl) * 8)
 					ecl = newEcl;
 			});
 			
-			// Create the data bit string by concatenating all segments
+			// Concatenate all segments to create the data bit string
 			let dataCapacityBits: int = QrCode.getNumDataCodewords(version, ecl) * 8;
 			let bb = new BitBuffer();
 			segs.forEach((seg: QrSegment) => {
@@ -308,7 +308,7 @@ namespace qrcodegen {
 				this.setFunctionModule(this.size - 1 - i, 8, getBit(data, i));
 			for (let i = 8; i < 15; i++)
 				this.setFunctionModule(8, this.size - 15 + i, getBit(data, i));
-			this.setFunctionModule(8, this.size - 8, true);
+			this.setFunctionModule(8, this.size - 8, true);  // Always black
 		}
 		
 		
@@ -443,10 +443,11 @@ namespace qrcodegen {
 		}
 		
 		
-		// XORs the data modules in this QR Code with the given mask pattern. Due to XOR's mathematical
+		// XORs the codeword modules in this QR Code with the given mask pattern.
-		// properties, calling applyMask(m) twice with the same value is equivalent to no change at all.
+		// The function modules must be marked and the codeword bits must be drawn
-		// This means it is possible to apply a mask, undo it, and try another mask. Note that a final
+		// before masking. Due to the arithmetic of XOR, calling applyMask() with
-		// well-formed QR Code symbol needs exactly one mask applied (not zero, not two, etc.).
+		// 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 applyMask(mask: int): void {
 			if (mask < 0 || mask > 7)
 				throw "Mask value out of range";