Added and updated code comments for members (mostly) and within functions (a few), in all languages.

cpp/QrCodeGeneratorDemo.cpp

@@ -38,6 +38,7 @@ static void printQr(const qrcodegen::QrCode &qr);
 
 
 
+// The main application program.
 int main(int argc, char **argv) {
 	doBasicDemo();
 	doVarietyDemo();

cpp/QrSegment.hpp

@@ -162,6 +162,7 @@ public:
 	/*---- Private constant ----*/
 private:
 	
+	/* Maps shifted ASCII codes to alphanumeric mode character codes. */
 	static const int8_t ALPHANUMERIC_ENCODING_TABLE[59];
 	
 };

java/io/nayuki/qrcodegen/QrSegment.java

@@ -215,6 +215,7 @@ public final class QrSegment {
 	/** Can test whether a string is encodable in alphanumeric mode (such as by using {@link #makeAlphanumeric(String)}). */
 	public static final Pattern ALPHANUMERIC_REGEX = Pattern.compile("[A-Z0-9 $%*+./:-]*");
 	
+	/** Maps shifted ASCII codes to alphanumeric mode character codes. */
 	private static final byte[] ALPHANUMERIC_ENCODING_TABLE = {
 		// SP,  !,  ",  #,  $,  %,  &,  ',  (,  ),  *,  +,  ,,  -,  .,  /,  0,  1,  2,  3,  4,  5,  6,  7,  8,  9,  :,  ;,  <,  =,  >,  ?,  @,  // ASCII codes 32 to 64
 		   36, -1, -1, -1, 37, 38, -1, -1, -1, -1, 39, 40, -1, 41, 42, 43,  0,  1,  2,  3,  4,  5,  6,  7,  8,  9, 44, -1, -1, -1, -1, -1, -1,  // Array indices 0 to 32

javascript/qrcodegen.js

@@ -26,14 +26,14 @@
 
 
 /* 
- * Module "qrcodegen". Public members inside this namespace:
+ * Module "qrcodegen", public members:
  * - Class QrCode:
  *   - Function encodeText(str text, QrCode.Ecc ecl) -> QrCode
  *   - Function encodeBinary(list<int> data, QrCode.Ecc ecl) -> QrCode
  *   - Function encodeSegments(list<QrSegment> segs, QrCode.Ecc ecl,
  *         int minVersion=1, int maxVersion=40, mask=-1, boostEcl=true) -> QrCode
  *   - Constructor QrCode(QrCode qr, int mask)
- *   - Constructor QrCode(list<int> bytes, int mask, int version, QrCode.Ecc ecl)
+ *   - Constructor QrCode(list<int> datacodewords, int mask, int version, QrCode.Ecc ecl)
  *   - Fields int version, size, mask
  *   - Field QrCode.Ecc errorCorrectionLevel
  *   - Method getModule(int x, int y) -> int
@@ -67,10 +67,10 @@ var qrcodegen = new function() {
 	 * from 1 to 40, all 4 error correction levels.
 	 * 
 	 * This constructor can be called in one of two ways:
-	 * - new QrCode(bytes, mask, version, errCorLvl):
+	 * - new QrCode(datacodewords, mask, version, errCorLvl):
 	 *       Creates a new QR Code symbol with the given version number, error correction level, binary data array,
 	 *       and mask number. This cumbersome constructor can be invoked directly by the user, but is considered
-	 *       to be even lower level than qrcodegen.encodeSegments().
+	 *       to be even lower level than QrCode.encodeSegments().
 	 * - new QrCode(qr, mask):
 	 *       Creates a new QR Code symbol based on the given existing object, but with a potentially different
 	 *       mask pattern. The version, error correction level, codewords, etc. of the newly created object are
@@ -81,7 +81,7 @@ var qrcodegen = new function() {
 		
 		/*---- Constructor ----*/
 		
-		// Handle simple scalar fields
+		// Check arguments and handle simple scalar fields
 		if (mask < -1 || mask > 7)
 			throw "Mask value out of range";
 		if (initData instanceof Array) {
@@ -590,7 +590,7 @@ var qrcodegen = new function() {
 	
 	/*---- Private static helper functions QrCode ----*/
 	
-	var QrCode = {};  // Private object to assign properties to
+	var QrCode = {};  // Private object to assign properties to. Not the same object as 'this.QrCode'.
 	
 	
 	// Returns a sequence of positions of the alignment patterns in ascending order. These positions are
@@ -676,15 +676,17 @@ var qrcodegen = new function() {
 	
 	/*---- Public helper enumeration ----*/
 	
+	// Private constructor.
 	function Ecc(ord, fb) {
+		// (Public) In the range 0 to 3 (unsigned 2-bit integer)
 		Object.defineProperty(this, "ordinal", {value:ord});
+		
 		Object.defineProperty(this, "formatBits", {value:fb});
 	}
 	
 	
 	/* 
-	 * A public helper enumeration that represents the error correction level used in a QR Code symbol.
-	 * The fields 'ordinal' and 'formatBits' are in the range 0 to 3 (unsigned 2-bit integer).
+	 * Represents the error correction level used in a QR Code symbol.
 	 */
 	this.QrCode.Ecc = {
 		// Constants declared in ascending order of error protection
@@ -725,7 +727,9 @@ var qrcodegen = new function() {
 	
 	/*---- Public static factory functions for QrSegment ----*/
 	
-	// Returns a segment representing the given binary data encoded in byte mode.
+	/* 
+	 * Returns a segment representing the given binary data encoded in byte mode.
+	 */
 	this.QrSegment.makeBytes = function(data) {
 		var bb = new BitBuffer();
 		data.forEach(function(b) {
@@ -735,7 +739,9 @@ var qrcodegen = new function() {
 	};
 	
 	
-	// Returns a segment representing the given string of decimal digits encoded in numeric mode.
+	/* 
+	 * Returns a segment representing the given string of decimal digits encoded in numeric mode.
+	 */
 	this.QrSegment.makeNumeric = function(digits) {
 		if (!QrSegment.NUMERIC_REGEX.test(digits))
 			throw "String contains non-numeric characters";
@@ -749,8 +755,11 @@ var qrcodegen = new function() {
 		return new this(this.Mode.NUMERIC, digits.length, bb.getBits());
 	};
 	
-	// Returns a segment representing the given text string encoded in alphanumeric mode. The characters allowed are:
-	// 0 to 9, A to Z (uppercase only), space, dollar, percent, asterisk, plus, hyphen, period, slash, colon.
+	
+	/* 
+	 * Returns a segment representing the given text string encoded in alphanumeric mode. The characters allowed are:
+	 * 0 to 9, A to Z (uppercase only), space, dollar, percent, asterisk, plus, hyphen, period, slash, colon.
+	 */
 	this.QrSegment.makeAlphanumeric = function(text) {
 		if (!QrSegment.ALPHANUMERIC_REGEX.test(text))
 			throw "String contains unencodable characters in alphanumeric mode";
@@ -803,7 +812,7 @@ var qrcodegen = new function() {
 	
 	/*---- Constants for QrSegment ----*/
 	
-	var QrSegment = {};  // Private object to assign properties to
+	var QrSegment = {};  // Private object to assign properties to. Not the same object as 'this.QrSegment'.
 	
 	// Can test whether a string is encodable in numeric mode (such as by using QrSegment.makeNumeric()).
 	QrSegment.NUMERIC_REGEX = /^[0-9]*$/;
@@ -811,6 +820,7 @@ var qrcodegen = new function() {
 	// Can test whether a string is encodable in alphanumeric mode (such as by using QrSegment.makeAlphanumeric()).
 	QrSegment.ALPHANUMERIC_REGEX = /^[A-Z0-9 $%*+.\/:-]*$/;
 	
+	// Maps shifted ASCII codes to alphanumeric mode character codes.
 	QrSegment.ALPHANUMERIC_ENCODING_TABLE = [
 		// SP,  !,  ",  #,  $,  %,  &,  ',  (,  ),  *,  +,  ,,  -,  .,  /,  0,  1,  2,  3,  4,  5,  6,  7,  8,  9,  :,  ;,  <,  =,  >,  ?,  @,  // ASCII codes 32 to 64
 		   36, -1, -1, -1, 37, 38, -1, -1, -1, -1, 39, 40, -1, 41, 42, 43,  0,  1,  2,  3,  4,  5,  6,  7,  8,  9, 44, -1, -1, -1, -1, -1, -1,  // Array indices 0 to 32
@@ -822,8 +832,7 @@ var qrcodegen = new function() {
 	/*---- Public helper enumeration ----*/
 	
 	/* 
-	 * A public helper enumeration that represents the mode field of a segment.
-	 * Objects are immutable. Provides methods to retrieve closely related values.
+	 * Represents the mode field of a segment. Immutable.
 	 */
 	this.QrSegment.Mode = {  // Constants
 		NUMERIC     : new Mode(0x1, [10, 12, 14]),
@@ -833,7 +842,7 @@ var qrcodegen = new function() {
 	};
 	
 	
-	// Private constructor for the enum.
+	// Private constructor.
 	function Mode(mode, ccbits) {
 		// An unsigned 4-bit integer value (range 0 to 15) representing the mode indicator bits for this mode object.
 		Object.defineProperty(this, "modeBits", {value:mode});

python/qrcodegen.py

@@ -26,14 +26,14 @@ import itertools, re, sys
 
 
 """
-Public members inside this module "qrcodegen":
+This module "qrcodegen", public members:
 - Class QrCode:
--   Function encode_text(str text, QrCode.Ecc ecl) -> QrCode
--   Function encode_binary(bytes data, QrCode.Ecc ecl) -> QrCode
+  - Function encode_text(str text, QrCode.Ecc ecl) -> QrCode
+  - Function encode_binary(bytes data, QrCode.Ecc ecl) -> QrCode
   - Function encode_segments(list<QrSegment> segs, QrCode.Ecc ecl,
         int minversion=1, int maxversion=40, mask=-1, boostecl=true) -> QrCode
   - Constructor QrCode(QrCode qr, int mask)
-  - Constructor QrCode(bytes bytes, int mask, int version, QrCode.Ecc ecl)
+  - Constructor QrCode(bytes datacodewords, int mask, int version, QrCode.Ecc ecl)
   - Method get_version() -> int
   - Method get_size() -> int
   - Method get_error_correction_level() -> QrCode.Ecc
@@ -141,14 +141,14 @@ class QrCode(object):
 		- QrCode(datacodewords=list<int>, mask=int, version=int, errcorlvl=QrCode.Ecc):
 		      Creates a new QR Code symbol with the given version number, error correction level, binary data array,
 		      and mask number. This cumbersome constructor can be invoked directly by the user, but is considered
-		      to be even lower level than qrcodegen.encode_segments().
+		      to be even lower level than QrCode.encode_segments().
 		- QrCode(qrcode=QrCode, mask=int):
 		      Creates a new QR Code symbol based on the given existing object, but with a potentially different
 		      mask pattern. The version, error correction level, codewords, etc. of the newly created object are
 		      all identical to the argument object; only the mask may differ.
 		In both cases, mask = -1 is for automatic choice or 0 to 7 for fixed choice."""
 		
-		# Handle simple scalar fields
+		# Check arguments and handle simple scalar fields
 		if not -1 <= mask <= 7:
 			raise ValueError("Mask value out of range")
 		if datacodewords is not None and qrcode is None:
@@ -586,7 +586,7 @@ class QrCode(object):
 			self.ordinal = i      # In the range 0 to 3 (unsigned 2-bit integer)
 			self.formatbits = fb  # In the range 0 to 3 (unsigned 2-bit integer)
 	
-	# Create the class constants outside the class
+	# Public constants. Create them outside the class.
 	Ecc.LOW      = Ecc(0, 1)
 	Ecc.MEDIUM   = Ecc(1, 0)
 	Ecc.QUARTILE = Ecc(2, 3)
@@ -717,13 +717,15 @@ class QrSegment(object):
 	# ---- Public helper enumeration ----
 	
 	class Mode(object):
-		"""The mode field of a segment. Immutable. Provides methods to retrieve closely related values."""
+		"""The mode field of a segment. Immutable."""
+		
 		# Private constructor
 		def __init__(self, modebits, charcounts):
 			self._modebits = modebits
 			self._charcounts = charcounts
 		
 		def get_mode_bits(self):
+			"""Returns an unsigned 4-bit integer value (range 0 to 15) representing the mode indicator bits for this mode object."""
 			return self._modebits
 		
 		def num_char_count_bits(self, ver):
@@ -733,7 +735,7 @@ class QrSegment(object):
 			elif 27 <= ver <= 40:  return self._charcounts[2]
 			else:  raise ValueError("Version number out of range")
 	
-	# Create the class constants outside the class
+	# Public constants. Create them outside the class.
 	Mode.NUMERIC      = Mode(0x1, (10, 12, 14))
 	Mode.ALPHANUMERIC = Mode(0x2, ( 9, 11, 13))
 	Mode.BYTE         = Mode(0x4, ( 8, 16, 16))