From 3ead3dbb840d9642adedd73dd0792c8e51ee4e6f Mon Sep 17 00:00:00 2001 From: Project Nayuki Date: Tue, 28 Aug 2018 21:08:00 +0000 Subject: [PATCH] Updated up to 8 comments in all language versions, but somewhat differently in each language. --- c/qrcodegen.c | 4 ++-- c/qrcodegen.h | 15 +++++++-------- cpp/QrCode.cpp | 4 ++-- cpp/QrCode.hpp | 7 +++---- cpp/QrSegment.hpp | 9 +++++---- java/io/nayuki/qrcodegen/QrCode.java | 16 ++++++++-------- java/io/nayuki/qrcodegen/QrSegment.java | 10 +++++----- javascript/qrcodegen.js | 18 ++++++++---------- python/qrcodegen.py | 20 ++++++++++---------- rust/src/lib.rs | 23 +++++++++++------------ typescript/qrcodegen.ts | 20 ++++++++++---------- 11 files changed, 71 insertions(+), 75 deletions(-) diff --git a/c/qrcodegen.c b/c/qrcodegen.c index ccc690f..19caed5 100644 --- a/c/qrcodegen.c +++ b/c/qrcodegen.c @@ -494,8 +494,8 @@ static void drawCodewords(const uint8_t data[], int dataLen, uint8_t qrcode[]) { setModule(qrcode, x, y, black); i++; } - // If there are any remainder bits (0 to 7), they are already - // set to 0/false/white when the grid of modules was initialized + // If this QR Code has any remainder bits (0 to 7), they were assigned as + // 0/false/white by the constructor and are left unchanged by this method } } } diff --git a/c/qrcodegen.h b/c/qrcodegen.h index c216619..25ddb06 100644 --- a/c/qrcodegen.h +++ b/c/qrcodegen.h @@ -73,10 +73,8 @@ enum qrcodegen_Mode { /* - * A segment of user/application data that a QR Code symbol can convey. - * Each segment has a mode, a character count, and character/general data that is - * already encoded as a sequence of bits. The maximum allowed bit length is 32767, - * because even the largest QR Code (version 40) has only 31329 modules. + * Represents a segment of character data, binary data, or control data. The maximum allowed + * bit length is 32767, because even the largest QR Code (version 40) has only 31329 modules. */ struct qrcodegen_Segment { // The mode indicator for this segment. @@ -219,9 +217,10 @@ struct qrcodegen_Segment qrcodegen_makeEci(long assignVal, uint8_t buf[]); /* - * Renders a QR Code symbol representing the given data segments at the given error correction - * level or higher. The smallest possible QR Code version is automatically chosen for the output. - * Returns true if QR Code creation succeeded, or false if the data is too long to fit in any version. + * Renders a QR Code symbol representing the given segments at the given error correction level. + * The smallest possible QR Code version is automatically chosen for the output. Returns true if + * QR Code creation succeeded, or false if the data is too long to fit in any version. The ECC level + * of the result may be higher than the ecl argument if it can be done without increasing the version. * This function allows the user to create a custom sequence of segments that switches * between modes (such as alphanumeric and binary) to encode text more efficiently. * This function is considered to be lower level than simply encoding text or binary data. @@ -234,7 +233,7 @@ bool qrcodegen_encodeSegments(const struct qrcodegen_Segment segs[], size_t len, /* - * Renders a QR Code symbol representing the given data segments with the given encoding parameters. + * Renders a QR Code symbol representing the given segments with the given encoding parameters. * Returns true if QR Code creation succeeded, or false if the data is too long to fit in the range of versions. * The smallest possible QR Code version within the given range is automatically chosen for the output. * This function allows the user to create a custom sequence of segments that switches diff --git a/cpp/QrCode.cpp b/cpp/QrCode.cpp index 2e0bedd..a6388cc 100644 --- a/cpp/QrCode.cpp +++ b/cpp/QrCode.cpp @@ -360,8 +360,8 @@ void QrCode::drawCodewords(const vector &data) { modules.at(y).at(x) = getBit(data.at(i >> 3), 7 - static_cast(i & 7)); i++; } - // If there are any remainder bits (0 to 7), they are already - // set to 0/false/white when the grid of modules was initialized + // If this QR Code has any remainder bits (0 to 7), they were assigned as + // 0/false/white by the constructor and are left unchanged by this method } } } diff --git a/cpp/QrCode.hpp b/cpp/QrCode.hpp index 15c4a25..0c71131 100644 --- a/cpp/QrCode.hpp +++ b/cpp/QrCode.hpp @@ -77,7 +77,7 @@ class QrCode final { /* - * Returns a QR Code symbol representing the given data segments with the given encoding parameters. + * Returns a QR Code symbol representing the given segments with the given encoding parameters. * The smallest possible QR Code version within the given range is automatically chosen for the output. * This function allows the user to create a custom sequence of segments that switches * between modes (such as alphanumeric and binary) to encode text more efficiently. @@ -154,9 +154,8 @@ class QrCode final { /* - * Based on the given number of border modules to add as padding, this returns a - * string whose contents represents an SVG XML file that depicts this QR Code symbol. - * Note that Unix newlines (\n) are always used, regardless of the platform. + * Returns a string of SVG XML code representing an image of this QR Code symbol with the given + * number of border modules. Note that Unix newlines (\n) are always used, regardless of the platform. */ public: std::string toSvgString(int border) const; diff --git a/cpp/QrSegment.hpp b/cpp/QrSegment.hpp index 2e83465..3cd0ec3 100644 --- a/cpp/QrSegment.hpp +++ b/cpp/QrSegment.hpp @@ -31,9 +31,8 @@ namespace qrcodegen { /* - * Represents a character string to be encoded in a QR Code symbol. Each segment has - * a mode, and a sequence of characters that is already encoded as a sequence of bits. - * Instances of this class are immutable. + * Represents a segment of character data, binary data, or control data + * to be put into a QR Code symbol. Instances of this class are immutable. * This segment class imposes no length restrictions, but QR Codes have restrictions. * Even in the most favorable conditions, a QR Code can only hold 7089 characters of data. * Any segment longer than this is meaningless for the purpose of generating QR Codes. @@ -58,8 +57,10 @@ class QrSegment final { /*-- Fields --*/ + // The mode indicator bits, which is a uint4 value (range 0 to 15). private: int modeBits; + // Three values for different version ranges. private: int numBitsCharCount[3]; @@ -150,7 +151,7 @@ class QrSegment final { /*---- Constructors ----*/ /* - * Creates a new QR Code data segment with the given parameters and data. + * Creates a new QR Code segment with the given parameters and data. */ public: QrSegment(Mode md, int numCh, const std::vector &dt); diff --git a/java/io/nayuki/qrcodegen/QrCode.java b/java/io/nayuki/qrcodegen/QrCode.java index 2dbe091..532d163 100644 --- a/java/io/nayuki/qrcodegen/QrCode.java +++ b/java/io/nayuki/qrcodegen/QrCode.java @@ -81,8 +81,9 @@ public final class QrCode { /** - * Returns a QR Code symbol representing the specified data segments at the specified error correction - * level or higher. The smallest possible QR Code version is automatically chosen for the output. + * Returns a QR Code symbol representing the specified segments at the specified error correction + * level. The smallest possible QR Code version is automatically chosen for the output. The ECC level + * of the result may be higher than the ecl argument if it can be done without increasing the version. *

This function allows the user to create a custom sequence of segments that switches * between modes (such as alphanumeric and binary) to encode text more efficiently. * This function is considered to be lower level than simply encoding text or binary data.

@@ -99,7 +100,7 @@ public final class QrCode { /** - * Returns a QR Code symbol representing the specified data segments with the specified encoding parameters. + * Returns a QR Code symbol representing the specified segments with the specified encoding parameters. * The smallest possible QR Code version within the specified range is automatically chosen for the output. *

This function allows the user to create a custom sequence of segments that switches * between modes (such as alphanumeric and binary) to encode text more efficiently. @@ -279,9 +280,8 @@ public final class QrCode { /** - * Based on the specified number of border modules to add as padding, this returns a - * string whose contents represents an SVG XML file that depicts this QR Code symbol. - * Note that Unix newlines (\n) are always used, regardless of the platform. + * Returns a string of SVG XML code representing an image of this QR Code symbol with the specified + * number of border modules. 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 @@ -495,8 +495,8 @@ public final class QrCode { modules[y][x] = getBit(data[i >>> 3], 7 - (i & 7)); i++; } - // If there are any remainder bits (0 to 7), they are already - // set to 0/false/white when the grid of modules was initialized + // If this QR Code has any remainder bits (0 to 7), they were assigned as + // 0/false/white by the constructor and are left unchanged by this method } } } diff --git a/java/io/nayuki/qrcodegen/QrSegment.java b/java/io/nayuki/qrcodegen/QrSegment.java index 37152f3..8328570 100644 --- a/java/io/nayuki/qrcodegen/QrSegment.java +++ b/java/io/nayuki/qrcodegen/QrSegment.java @@ -31,9 +31,8 @@ import java.util.regex.Pattern; /** - * Represents a character string to be encoded in a QR Code symbol. Each segment has - * a mode, and a sequence of characters that is already encoded as a sequence of bits. - * Instances of this class are immutable. + * Represents a segment of character data, binary data, or control data + * to be put into a QR Code symbol. Instances of this class are immutable. *

This segment class imposes no length restrictions, but QR Codes have restrictions. * Even in the most favorable conditions, a QR Code can only hold 7089 characters of data. * Any segment longer than this is meaningless for the purpose of generating QR Codes.

@@ -169,7 +168,7 @@ public final class QrSegment { /*---- Constructor ----*/ /** - * Constructs a QR Code data segment with the specified parameters and data. + * Constructs a QR Code segment with the specified parameters and data. * @param md the mode, which is not {@code null} * @param numCh the data length in characters, which is non-negative * @param data the data bits of this segment, which is not {@code null} @@ -247,9 +246,10 @@ public final class QrSegment { /*-- Fields --*/ - /** An unsigned 4-bit integer value (range 0 to 15) representing the mode indicator bits for this mode object. */ + /** The mode indicator bits, which is a uint4 value (range 0 to 15). */ final int modeBits; + /** Three values for different version ranges. */ private final int[] numBitsCharCount; diff --git a/javascript/qrcodegen.js b/javascript/qrcodegen.js index 6ff31e1..fc09624 100644 --- a/javascript/qrcodegen.js +++ b/javascript/qrcodegen.js @@ -164,9 +164,8 @@ var qrcodegen = new function() { } }; - // Based on the given number of border modules to add as padding, this returns a - // string whose contents represents an SVG XML file that depicts this QR Code symbol. - // Note that Unix newlines (\n) are always used, regardless of the platform. + // Returns a string of SVG XML code representing an image of this QR Code symbol with the given + // number of border modules. Note that Unix newlines (\n) are always used, regardless of the platform. this.toSvgString = function(border) { if (border < 0) throw "Border must be non-negative"; @@ -370,8 +369,8 @@ var qrcodegen = new function() { modules[y][x] = getBit(data[i >>> 3], 7 - (i & 7)); i++; } - // If there are any remainder bits (0 to 7), they are already - // set to 0/false/white when the grid of modules was initialized + // If this QR Code has any remainder bits (0 to 7), they were assigned as + // 0/false/white by the constructor and are left unchanged by this method } } } @@ -541,7 +540,7 @@ var qrcodegen = new function() { /* - * Returns a QR Code symbol representing the given data segments with the given encoding parameters. + * Returns a QR Code symbol representing the given segments with the given encoding parameters. * The smallest possible QR Code version within the given range is automatically chosen for the output. * This function allows the user to create a custom sequence of segments that switches * between modes (such as alphanumeric and binary) to encode text more efficiently. @@ -697,9 +696,8 @@ var qrcodegen = new function() { /*---- Data segment class ----*/ /* - * A public class that represents a character string to be encoded in a QR Code symbol. - * Each segment has a mode, and a sequence of characters that is already encoded as - * a sequence of bits. Instances of this class are immutable. + * Represents a segment of character data, binary data, or control data + * to be put into a QR Code symbol. Instances of this class are immutable. * This segment class imposes no length restrictions, but QR Codes have restrictions. * Even in the most favorable conditions, a QR Code can only hold 7089 characters of data. * Any segment longer than this is meaningless for the purpose of generating QR Codes. @@ -856,7 +854,7 @@ var qrcodegen = new function() { // Private constructor. function Mode(mode, ccbits) { - // (Package-private) An unsigned 4-bit integer value (range 0 to 15) representing the mode indicator bits for this mode object. + // (Package-private) The mode indicator bits, which is a uint4 value (range 0 to 15). Object.defineProperty(this, "modeBits", {value:mode}); // (Package-private) Returns the bit width of the segment character count field for this mode object at the given version number. diff --git a/python/qrcodegen.py b/python/qrcodegen.py index 4435195..fbf5a13 100644 --- a/python/qrcodegen.py +++ b/python/qrcodegen.py @@ -90,7 +90,7 @@ class QrCode(object): @staticmethod def encode_segments(segs, ecl, minversion=1, maxversion=40, mask=-1, boostecl=True): - """Returns a QR Code symbol representing the given data segments with the given encoding parameters. + """Returns a QR Code symbol representing the given segments with the given encoding parameters. The smallest possible QR Code version within the given range is automatically chosen for the output. This function allows the user to create a custom sequence of segments that switches between modes (such as alphanumeric and binary) to encode text more efficiently. @@ -223,8 +223,8 @@ class QrCode(object): # ---- Public instance methods ---- def to_svg_str(self, border): - """Based on the given number of border modules to add as padding, this returns a - string whose contents represents an SVG XML file that depicts this QR Code symbol.""" + """Returns a string of SVG XML code representing an image of this QR Code symbol with the given + number of border modules. Note that Unix newlines (\n) are always used, regardless of the platform.""" if border < 0: raise ValueError("Border must be non-negative") parts = [] @@ -403,8 +403,8 @@ class QrCode(object): if not self._isfunction[y][x] and i < len(data) * 8: self._modules[y][x] = _get_bit(data[i >> 3], 7 - (i & 7)) i += 1 - # If there are any remainder bits (0 to 7), they are already - # set to 0/false/white when the grid of modules was initialized + # If this QR Code has any remainder bits (0 to 7), they were assigned as + # 0/false/white by the constructor and are left unchanged by this method assert i == len(data) * 8 @@ -583,9 +583,8 @@ class QrCode(object): # ---- Data segment class ---- class QrSegment(object): - """Represents a character string to be encoded in a QR Code symbol. Each segment has - a mode, and a sequence of characters that is already encoded as a sequence of bits. - Instances of this class are immutable. + """Represents a segment of character data, binary data, or control data + to be put into a QR Code symbol. Instances of this class are immutable. This segment class imposes no length restrictions, but QR Codes have restrictions. Even in the most favorable conditions, a QR Code can only hold 7089 characters of data. Any segment longer than this is meaningless for the purpose of generating QR Codes.""" @@ -676,6 +675,7 @@ class QrSegment(object): # ---- Constructor ---- def __init__(self, mode, numch, bitdata): + """Creates a new QR Code segment with the given parameters and data.""" if numch < 0 or not isinstance(mode, QrSegment.Mode): raise ValueError() self._mode = mode @@ -729,8 +729,8 @@ class QrSegment(object): # Private constructor def __init__(self, modebits, charcounts): - self._modebits = modebits - self._charcounts = charcounts + self._modebits = modebits # The mode indicator bits, which is a uint4 value (range 0 to 15) + self._charcounts = charcounts # Three values for different version ranges # Package-private method def get_mode_bits(self): diff --git a/rust/src/lib.rs b/rust/src/lib.rs index 1f6bf23..523d87d 100644 --- a/rust/src/lib.rs +++ b/rust/src/lib.rs @@ -82,8 +82,9 @@ impl QrCode { } - // Returns a QR Code symbol representing the given data segments at the given error correction - // level or higher. The smallest possible QR Code version is automatically chosen for the output. + // Returns a QR Code symbol representing the given segments at the given error correction level. + // The smallest possible QR Code version is automatically chosen for the output. The ECC level + // of the result may be higher than the ecl argument if it can be done without increasing the version. // This function allows the user to create a custom sequence of segments that switches // between modes (such as alphanumeric and binary) to encode text more efficiently. // This function is considered to be lower level than simply encoding text or binary data. @@ -93,7 +94,7 @@ impl QrCode { } - // Returns a QR Code symbol representing the given data segments with the given encoding parameters. + // Returns a QR Code symbol representing the given segments with the given encoding parameters. // The smallest possible QR Code version within the given range is automatically chosen for the output. // This function allows the user to create a custom sequence of segments that switches // between modes (such as alphanumeric and binary) to encode text more efficiently. @@ -239,9 +240,8 @@ impl QrCode { } - // Based on the given number of border modules to add as padding, this returns a - // string whose contents represents an SVG XML file that depicts this QR Code symbol. - // Note that Unix newlines (\n) are always used, regardless of the platform. + // Returns a string of SVG XML code representing an image of this QR Code symbol with the given + // number of border modules. Note that Unix newlines (\n) are always used, regardless of the platform. pub fn to_svg_string(&self, border: i32) -> String { assert!(border >= 0, "Border must be non-negative"); let mut result = String::new(); @@ -468,8 +468,8 @@ impl QrCode { *self.module_mut(x, y) = get_bit(data[i >> 3] as u32, 7 - ((i & 7) as i32)); i += 1; } - // If there are any remainder bits (0 to 7), they are already - // set to 0/false/white when the grid of modules was initialized + // If this QR Code has any remainder bits (0 to 7), they were assigned as + // 0/false/white by the constructor and are left unchanged by this method } } right -= 2; @@ -826,9 +826,8 @@ impl ReedSolomonGenerator { /*---- QrSegment functionality ----*/ -// Represents a character string to be encoded in a QR Code symbol. -// Each segment has a mode, and a sequence of characters that is already -// encoded as a sequence of bits. Instances of this struct are immutable. +// Represents a segment of character data, binary data, or control data +// to be put into a QR Code symbol. Instances of this class are immutable. pub struct QrSegment { // The mode indicator for this segment. @@ -942,7 +941,7 @@ impl QrSegment { } - // Creates a new QR Code data segment with the given parameters and data. + // Creates a new QR Code segment with the given parameters and data. pub fn new(mode: QrSegmentMode, numchars: usize, data: Vec) -> Self { Self { mode: mode, diff --git a/typescript/qrcodegen.ts b/typescript/qrcodegen.ts index ffa3d67..1c626c7 100644 --- a/typescript/qrcodegen.ts +++ b/typescript/qrcodegen.ts @@ -67,7 +67,7 @@ namespace qrcodegen { } - // Returns a QR Code symbol representing the given data segments with the given encoding parameters. + // Returns a QR Code symbol representing the given segments with the given encoding parameters. // The smallest possible QR Code version within the given range is automatically chosen for the output. // This function allows the user to create a custom sequence of segments that switches // between modes (such as alphanumeric and binary) to encode text more efficiently. @@ -231,9 +231,8 @@ namespace qrcodegen { } - // Based on the given number of border modules to add as padding, this returns a - // string whose contents represents an SVG XML file that depicts this QR Code symbol. - // Note that Unix newlines (\n) are always used, regardless of the platform. + // Returns a string of SVG XML code representing an image of this QR Code symbol with the given + // number of border modules. Note that Unix newlines (\n) are always used, regardless of the platform. public toSvgString(border: int): string { if (border < 0) throw "Border must be non-negative"; @@ -439,8 +438,8 @@ namespace qrcodegen { this.modules[y][x] = getBit(data[i >>> 3], 7 - (i & 7)); i++; } - // If there are any remainder bits (0 to 7), they are already - // set to 0/false/white when the grid of modules was initialized + // If this QR Code has any remainder bits (0 to 7), they were assigned as + // 0/false/white by the constructor and are left unchanged by this method } } } @@ -650,9 +649,8 @@ namespace qrcodegen { /*---- Data segment class ----*/ /* - * A public class that represents a character string to be encoded in a QR Code symbol. - * Each segment has a mode, and a sequence of characters that is already encoded as - * a sequence of bits. Instances of this class are immutable. + * Represents a segment of character data, binary data, or control data + * to be put into a QR Code symbol. Instances of this class are immutable. * This segment class imposes no length restrictions, but QR Codes have restrictions. * Even in the most favorable conditions, a QR Code can only hold 7089 characters of data. * Any segment longer than this is meaningless for the purpose of generating QR Codes. @@ -750,6 +748,7 @@ namespace qrcodegen { /*-- Constructor --*/ + // Creates a new QR Code segment with the given parameters and data. public constructor(mode: QrSegment.Mode, numChars: int, bitData: Array) { if (numChars < 0) throw "Invalid argument"; @@ -987,9 +986,10 @@ namespace qrcodegen.QrSegment { /*-- Fields --*/ - // An unsigned 4-bit integer value (range 0 to 15) representing the mode indicator bits for this mode object. + // The mode indicator bits, which is a uint4 value (range 0 to 15). public readonly modeBits: int; + // Three values for different version ranges. private readonly numBitsCharCount: [int,int,int];