From be316029aa21fa7775a48ceb84957d85134763b1 Mon Sep 17 00:00:00 2001 From: Nayuki Minase Date: Wed, 20 Apr 2016 20:27:41 +0000 Subject: [PATCH] Added and updated code comments for members (mostly) and within functions (a few), in all languages. --- cpp/QrCodeGeneratorDemo.cpp | 1 + cpp/QrSegment.hpp | 1 + java/io/nayuki/qrcodegen/QrSegment.java | 1 + javascript/qrcodegen.js | 41 +++++++++++++++---------- python/qrcodegen.py | 20 ++++++------ 5 files changed, 39 insertions(+), 25 deletions(-) diff --git a/cpp/QrCodeGeneratorDemo.cpp b/cpp/QrCodeGeneratorDemo.cpp index f003a0c..569d205 100644 --- a/cpp/QrCodeGeneratorDemo.cpp +++ b/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(); diff --git a/cpp/QrSegment.hpp b/cpp/QrSegment.hpp index 79274c4..cc8db37 100644 --- a/cpp/QrSegment.hpp +++ b/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]; }; diff --git a/java/io/nayuki/qrcodegen/QrSegment.java b/java/io/nayuki/qrcodegen/QrSegment.java index 4d441da..c41792a 100644 --- a/java/io/nayuki/qrcodegen/QrSegment.java +++ b/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 diff --git a/javascript/qrcodegen.js b/javascript/qrcodegen.js index 4e36ab7..0b3c9f6 100644 --- a/javascript/qrcodegen.js +++ b/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 data, QrCode.Ecc ecl) -> QrCode * - Function encodeSegments(list segs, QrCode.Ecc ecl, * int minVersion=1, int maxVersion=40, mask=-1, boostEcl=true) -> QrCode * - Constructor QrCode(QrCode qr, int mask) - * - Constructor QrCode(list bytes, int mask, int version, QrCode.Ecc ecl) + * - Constructor QrCode(list 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}); diff --git a/python/qrcodegen.py b/python/qrcodegen.py index 284f522..73ae851 100644 --- a/python/qrcodegen.py +++ b/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 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, 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))