Updated and synchronized documentation comments for QrCode class's constructor and static factory functions, in all languages.

c/qrcodegen.h

@@ -256,8 +256,8 @@ struct qrcodegen_Segment qrcodegen_makeEci(long assignVal, uint8_t buf[]);
  * 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.
+ * between modes (such as alphanumeric and byte) to encode text in less space.
+ * This is a low-level API; the high-level API is qrcodegen_encodeText() and qrcodegen_encodeBinary().
  * To save memory, the segments' data buffers can alias/overlap tempBuffer, and will
  * result in them being clobbered, but the QR Code output will still be correct.
  * But the qrcode array must not overlap tempBuffer or any segment's data buffer.
@@ -269,10 +269,14 @@ bool qrcodegen_encodeSegments(const struct qrcodegen_Segment segs[], size_t len,
 /* 
  * Renders a QR Code 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.
+ * The smallest possible QR Code version within the given range is automatically
+ * chosen for the output. Iff boostEcl is true, then the ECC level of the result
+ * may be higher than the ecl argument if it can be done without increasing the
+ * version. The mask number is either between 0 to 7 (inclusive) to force that
+ * mask, or -1 to automatically choose an appropriate mask (which may be slow).
  * 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.
+ * between modes (such as alphanumeric and byte) to encode text in less space.
+ * This is a low-level API; the high-level API is qrcodegen_encodeText() and qrcodegen_encodeBinary().
  * To save memory, the segments' data buffers can alias/overlap tempBuffer, and will
  * result in them being clobbered, but the QR Code output will still be correct.
  * But the qrcode array must not overlap tempBuffer or any segment's data buffer.

cpp/QrCode.hpp

@@ -80,7 +80,7 @@ class QrCode final {
 	
 	
 	/* 
-	 * Returns a QR Code representing the given binary data string at the given error correction level.
+	 * Returns a QR Code representing the given binary data at the given error correction level.
 	 * This function always encodes using the binary segment mode, not any text mode. The maximum number of
 	 * bytes allowed is 2953. 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.
@@ -92,10 +92,14 @@ class QrCode final {
 	
 	/* 
 	 * Returns a QR Code 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.
+	 * The smallest possible QR Code version within the given range is automatically
+	 * chosen for the output. Iff boostEcl is true, then the ECC level of the result
+	 * may be higher than the ecl argument if it can be done without increasing the
+	 * version. The mask number is either between 0 to 7 (inclusive) to force that
+	 * mask, or -1 to automatically choose an appropriate mask (which may be slow).
 	 * 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.
+	 * between modes (such as alphanumeric and byte) to encode text in less space.
+	 * This is a mid-level API; the high-level API is encodeText() and encodeBinary().
 	 */
 	public: static QrCode encodeSegments(const std::vector<QrSegment> &segs, Ecc ecl,
 		int minVersion=1, int maxVersion=40, int mask=-1, bool boostEcl=true);  // All optional parameters
@@ -135,9 +139,10 @@ class QrCode final {
 	/*---- Constructor (low level) ----*/
 	
 	/* 
-	 * Creates a new QR Code with the given version number, error correction level, binary data array,
-	 * and mask number. This is a cumbersome low-level constructor that should not be invoked directly by the user.
-	 * To go one level up, see the encodeSegments() function.
+	 * Creates a new QR Code with the given version number,
+	 * error correction level, data codeword bytes, and mask number.
+	 * This is a low-level API that most users should not use directly.
+	 * A mid-level API is the encodeSegments() function.
 	 */
 	public: QrCode(int ver, Ecc ecl, const std::vector<std::uint8_t> &dataCodewords, int mask);
 	

java/io/nayuki/qrcodegen/QrCode.java

@@ -75,7 +75,7 @@ public final class QrCode {
 	
 	
 	/**
-	 * Returns a QR Code representing the specified binary data string at the specified error correction level.
+	 * Returns a QR Code representing the specified binary data at the specified error correction level.
 	 * This function always encodes using the binary segment mode, not any text mode. The maximum number of
 	 * bytes allowed is 2953. 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.
@@ -101,8 +101,9 @@ public final class QrCode {
 	 * 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.
 	 * <p>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.</p>
+	 * between modes (such as alphanumeric and byte) to encode text in less space.
+	 * This is a mid-level API; the high-level API is {@link #encodeText(String,Ecc)}
+	 * and {@link #encodeBinary(byte[],Ecc)}.</p>
 	 * @param segs the segments to encode
 	 * @param ecl the error correction level to use (will be boosted)
 	 * @return a QR Code representing the segments
@@ -117,10 +118,15 @@ public final class QrCode {
 	
 	/**
 	 * Returns a QR Code 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.
+	 * The smallest possible QR Code version within the specified range is automatically
+	 * chosen for the output. Iff boostEcl is {@code true}, then the ECC level of the
+	 * result may be higher than the ecl argument if it can be done without increasing
+	 * the version. The mask number is either between 0 to 7 (inclusive) to force that
+	 * mask, or &#x2212;1 to automatically choose an appropriate mask (which may be slow).
 	 * <p>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.</p>
+	 * between modes (such as alphanumeric and byte) to encode text in less space.
+	 * This is a mid-level API; the high-level API is {@link #encodeText(String,Ecc)}
+	 * and {@link #encodeBinary(byte[],Ecc)}.</p>
 	 * @param segs the segments to encode
 	 * @param ecl the error correction level to use (may be boosted)
 	 * @param minVersion the minimum allowed version of the QR symbol (at least 1)
@@ -216,9 +222,10 @@ public final class QrCode {
 	/*---- Constructor (low level) ----*/
 	
 	/**
-	 * Constructs a QR Code with the specified version number, error correction level, binary data array, and mask number.
-	 * <p>This is a cumbersome low-level constructor that should not be invoked directly by the user.
-	 * To go one level up, see the {@link #encodeSegments(List,Ecc,int,int,int,boolean)} function.</p>
+	 * Constructs a QR Code with the specified version number,
+	 * error correction level, data codeword bytes, and mask number.
+	 * <p>This is a low-level API that most users should not use directly. A mid-level
+	 * API is the {@link #encodeSegments(List,Ecc,int,int,int,boolean)} function.</p>
 	 * @param ver the version number to use, which must be in the range 1 to 40 (inclusive)
 	 * @param ecl the error correction level to use
 	 * @param dataCodewords the bytes representing segments to encode (without ECC)

javascript/qrcodegen.js

@@ -75,9 +75,10 @@ var qrcodegen = new function() {
 	 *   supply the appropriate version number, and call the QrCode() constructor.
 	 * (Note that all ways require supplying the desired error correction level.)
 	 * 
-	 * This constructor creates a new QR Code with the given version number, error correction level, binary data array,
-	 * and mask number. mask = -1 is for automatic choice, or 0 to 7 for fixed choice. This is a cumbersome low-level constructor
-	 * that should not be invoked directly by the user. To go one level up, see the QrCode.encodeSegments() function.
+	 * This constructor creates a new QR Code with the given version number,
+	 * error correction level, data codeword bytes, and mask number.
+	 * This is a low-level API that most users should not use directly.
+	 * A mid-level API is the encodeSegments() function.
 	 */
 	this.QrCode = function(version, errCorLvl, dataCodewords, mask) {
 		
@@ -541,7 +542,7 @@ var qrcodegen = new function() {
 	
 	
 	/* 
-	 * Returns a QR Code representing the given binary data string at the given error correction level.
+	 * Returns a QR Code representing the given binary data at the given error correction level.
 	 * This function always encodes using the binary segment mode, not any text mode. The maximum number of
 	 * bytes allowed is 2953. 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.
@@ -556,10 +557,14 @@ var qrcodegen = new function() {
 	
 	/* 
 	 * Returns a QR Code 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.
+	 * The smallest possible QR Code version within the given range is automatically
+	 * chosen for the output. Iff boostEcl is true, then the ECC level of the result
+	 * may be higher than the ecl argument if it can be done without increasing the
+	 * version. The mask number is either between 0 to 7 (inclusive) to force that
+	 * mask, or -1 to automatically choose an appropriate mask (which may be slow).
 	 * 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.
+	 * between modes (such as alphanumeric and byte) to encode text in less space.
+	 * This is a mid-level API; the high-level API is encodeText() and encodeBinary().
 	 */
 	this.QrCode.encodeSegments = function(segs, ecl, minVersion, maxVersion, mask, boostEcl) {
 		if (minVersion == undefined) minVersion = MIN_VERSION;

python/qrcodegen.py

@@ -91,7 +91,7 @@ class QrCode(object):
 	
 	@staticmethod
 	def encode_binary(data, ecl):
-		"""Returns a QR Code representing the given binary data string at the given error correction level.
+		"""Returns a QR Code representing the given binary data at the given error correction level.
 		This function always encodes using the binary segment mode, not any text mode. The maximum number of
 		bytes allowed is 2953. 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."""
@@ -105,10 +105,14 @@ class QrCode(object):
 	@staticmethod
 	def encode_segments(segs, ecl, minversion=1, maxversion=40, mask=-1, boostecl=True):
 		"""Returns a QR Code 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.
+		The smallest possible QR Code version within the given range is automatically
+		chosen for the output. Iff boostecl is true, then the ECC level of the result
+		may be higher than the ecl argument if it can be done without increasing the
+		version. The mask number is either between 0 to 7 (inclusive) to force that
+		mask, or -1 to automatically choose an appropriate mask (which may be slow).
 		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."""
+		between modes (such as alphanumeric and byte) to encode text in less space.
+		This is a mid-level API; the high-level API is encode_text() and encode_binary()."""
 		
 		if not (QrCode.MIN_VERSION <= minversion <= maxversion <= QrCode.MAX_VERSION) or not (-1 <= mask <= 7):
 			raise ValueError("Invalid value")
@@ -157,9 +161,10 @@ class QrCode(object):
 	# ---- Constructor (low level) ----
 	
 	def __init__(self, version, errcorlvl, datacodewords, mask):
-		"""Creates a new QR Code with the given version number, error correction level, binary data array,
-		and mask number. mask = -1 is for automatic choice, or 0 to 7 for fixed choice. This is a cumbersome low-level constructor
-		that should not be invoked directly by the user. To go one level up, see the QrCode.encode_segments() function."""
+		"""Creates a new QR Code with the given version number,
+		error correction level, data codeword bytes, and mask number.
+		This is a low-level API that most users should not use directly.
+		A mid-level API is the encode_segments() function."""
 		
 		# Check scalar arguments and set fields
 		if not (QrCode.MIN_VERSION <= version <= QrCode.MAX_VERSION):

rust/src/lib.rs

@@ -90,7 +90,7 @@ impl QrCode {
 	}
 	
 	
-	// Returns a QR Code representing the given binary data string at the given error correction level.
+	// Returns a QR Code representing the given binary data at the given error correction level.
 	// This function always encodes using the binary segment mode, not any text mode. The maximum number of
 	// bytes allowed is 2953. 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.
@@ -107,8 +107,8 @@ impl QrCode {
 	// 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.
+	// between modes (such as alphanumeric and byte) to encode text in less space.
+	// This is a mid-level API; the high-level API is encode_text() and encode_binary().
 	// Returns a wrapped QrCode if successful, or None if the data is too long to fit in any version at the given ECC level.
 	pub fn encode_segments(segs: &[QrSegment], ecl: QrCodeEcc) -> Option<Self> {
 		QrCode::encode_segments_advanced(segs, ecl, QrCode_MIN_VERSION, QrCode_MAX_VERSION, None, true)
@@ -116,10 +116,14 @@ impl QrCode {
 	
 	
 	// Returns a QR Code 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.
+	// The smallest possible QR Code version within the given range is automatically
+	// chosen for the output. Iff boostecl is true, then the ECC level of the result
+	// may be higher than the ecl argument if it can be done without increasing the
+	// version. The mask number is either between 0 to 7 (inclusive) to force that
+	// mask, or -1 to automatically choose an appropriate mask (which may be slow).
 	// 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.
+	// between modes (such as alphanumeric and byte) to encode text in less space.
+	// This is a mid-level API; the high-level API is encodeText() and encodeBinary().
 	// Returns a wrapped QrCode if successful, or None if the data is too long to fit
 	// in any version in the given range at the given ECC level.
 	pub fn encode_segments_advanced(segs: &[QrSegment], mut ecl: QrCodeEcc,
@@ -189,9 +193,10 @@ impl QrCode {
 	
 	/*---- Constructor (low level) ----*/
 	
-	// Creates a new QR Code with the given version number, error correction level,
-	// binary data array, and mask number. This is a cumbersome low-level constructor that
-	// should not be invoked directly by the user. To go one level up, see the encode_segments() function.
+	// Creates a new QR Code with the given version number,
+	// error correction level, data codeword bytes, and mask number.
+	// This is a low-level API that most users should not use directly.
+	// A mid-level API is the encode_segments() function.
 	pub fn encode_codewords(ver: Version, ecl: QrCodeEcc, datacodewords: &[u8], mask: Option<Mask>) -> Self {
 		// Initialize fields
 		let size: usize = (ver.value() as usize) * 4 + 17;

typescript/qrcodegen.ts

@@ -64,7 +64,7 @@ namespace qrcodegen {
 		}
 		
 		
-		// Returns a QR Code representing the given binary data string at the given error correction level.
+		// Returns a QR Code representing the given binary data at the given error correction level.
 		// This function always encodes using the binary segment mode, not any text mode. The maximum number of
 		// bytes allowed is 2953. 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.
@@ -77,10 +77,14 @@ namespace qrcodegen {
 		/*-- Static factory functions (mid level) --*/
 		
 		// Returns a QR Code 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.
+		// The smallest possible QR Code version within the given range is automatically
+		// chosen for the output. Iff boostEcl is true, then the ECC level of the result
+		// may be higher than the ecl argument if it can be done without increasing the
+		// version. The mask number is either between 0 to 7 (inclusive) to force that
+		// mask, or -1 to automatically choose an appropriate mask (which may be slow).
 		// 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.
+		// between modes (such as alphanumeric and byte) to encode text in less space.
+		// This is a mid-level API; the high-level API is encodeText() and encodeBinary().
 		public static encodeSegments(segs: Array<QrSegment>, ecl: QrCode.Ecc,
 				minVersion: int = 1, maxVersion: int = 40,
 				mask: int = -1, boostEcl: boolean = true): QrCode {
@@ -153,9 +157,10 @@ namespace qrcodegen {
 		
 		/*-- Constructor (low level) and fields --*/
 		
-		// Creates a new QR Code with the given version number, error correction level, binary data array,
-		// and mask number. mask = -1 is for automatic choice, or 0 to 7 for fixed choice. This is a cumbersome low-level constructor
-		// that should not be invoked directly by the user. To go one level up, see the QrCode.encodeSegments() function.
+		// Creates a new QR Code with the given version number,
+		// error correction level, data codeword bytes, and mask number.
+		// This is a low-level API that most users should not use directly.
+		// A mid-level API is the encodeSegments() function.
 		public constructor(
 				// The version number of this QR Code, which is between 1 and 40 (inclusive).
 				// This determines the size of this barcode.