Updated documentation comments for 3 functions in all language versions.

cpp/QrCode.hpp

@@ -70,6 +70,7 @@ public:
 	 * Returns a QR Code symbol representing the given Unicode text string at the given error correction level.
 	 * As a conservative upper bound, this function is guaranteed to succeed for strings that have 738 or fewer Unicode
 	 * code points (not UTF-16 code units). 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.
 	 */
 	static QrCode encodeText(const char *text, const Ecc &ecl);
 	
@@ -78,6 +79,7 @@ public:
 	 * Returns a QR Code symbol representing the given binary data string 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.
 	 */
 	static QrCode encodeBinary(const std::vector<uint8_t> &data, const Ecc &ecl);
 	
@@ -126,9 +128,9 @@ private:
 public:
 	
 	/* 
-	 * Creates a new QR Code symbol with the given version number, error correction level, binary data string, and mask number.
+	 * Creates a new QR Code symbol with the given version number, error correction level, binary data array,
-	 * This cumbersome constructor can be invoked directly by the user, but is considered
+	 * and mask number. This is a cumbersome low-level constructor that should not be invoked directly by the user.
-	 * to be even lower level than encodeSegments().
+	 * To go one level up, see the encodeSegments() function.
 	 */
 	QrCode(int ver, const Ecc &ecl, const std::vector<uint8_t> &dataCodewords, int mask);
 	

java/io/nayuki/qrcodegen/QrCode.java

@@ -43,8 +43,9 @@ public final class QrCode {
 	 * Returns a QR Code symbol representing the specified Unicode text string at the specified error correction level.
 	 * As a conservative upper bound, this function is guaranteed to succeed for strings that have 738 or fewer Unicode
 	 * code points (not UTF-16 code units). 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.
 	 * @param text the text to be encoded, which can be any Unicode string
-	 * @param ecl the error correction level to use
+	 * @param ecl the error correction level to use (will be boosted)
 	 * @return a QR Code representing the text
 	 * @throws NullPointerException if the text or error correction level is {@code null}
 	 * @throws IllegalArgumentException if the text fails to fit in the largest version QR Code, which means it is too long
@@ -61,8 +62,9 @@ public final class QrCode {
 	 * Returns a QR Code symbol representing the specified binary data string 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.
 	 * @param data the binary data to encode
-	 * @param ecl the error correction level to use
+	 * @param ecl the error correction level to use (will be boosted)
 	 * @return a QR Code representing the binary data
 	 * @throws NullPointerException if the data or error correction level is {@code null}
 	 * @throws IllegalArgumentException if the data fails to fit in the largest version QR Code, which means it is too long
@@ -187,9 +189,9 @@ public final class QrCode {
 	/*---- Constructors ----*/
 	
 	/**
-	 * Creates a new QR Code symbol with the specified version number, error correction level, binary data string, and mask number.
+	 * Creates a new QR Code symbol with the specified version number, error correction level, binary data array, and mask number.
-	 * <p>This cumbersome constructor can be invoked directly by the user, but is considered
+	 * <p>This is a cumbersome low-level constructor that should not be invoked directly by the user.
-	 * to be even lower level than {@link #encodeSegments(List,Ecc)}.</p>
+	 * To go one level up, see the {@link #encodeSegments(List,Ecc)} 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 raw binary user data to encode

javascript/qrcodegen.js

@@ -68,8 +68,8 @@ var qrcodegen = new function() {
 	 * This constructor can be called in one of two ways:
 	 * - 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
+	 *       and mask number. This is a cumbersome low-level constructor that should not be invoked directly by the user.
-	 *       to be even lower level than QrCode.encodeSegments().
+	 *       To go one level up, see the QrCode.encodeSegments() function.
 	 * - 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
@@ -541,6 +541,7 @@ var qrcodegen = new function() {
 	 * Returns a QR Code symbol representing the given Unicode text string at the given error correction level.
 	 * As a conservative upper bound, this function is guaranteed to succeed for strings that have 738 or fewer Unicode
 	 * code points (not UTF-16 code units). 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.QrCode.encodeText = function(text, ecl) {
 		var segs = qrcodegen.QrSegment.makeSegments(text);
@@ -552,6 +553,7 @@ var qrcodegen = new function() {
 	 * Returns a QR Code symbol representing the given binary data string 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.
 	 */
 	this.QrCode.encodeBinary = function(data, ecl) {
 		var seg = qrcodegen.QrSegment.makeBytes(data);

python/qrcodegen.py

@@ -70,7 +70,8 @@ class QrCode(object):
 	def encode_text(text, ecl):
 		"""Returns a QR Code symbol representing the given Unicode text string at the given error correction level.
 		As a conservative upper bound, this function is guaranteed to succeed for strings that have 738 or fewer Unicode
-		code points (not UTF-16 code units). The smallest possible QR Code version is automatically chosen for the output."""
+		code points (not UTF-16 code units). 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."""
 		segs = QrSegment.make_segments(text)
 		return QrCode.encode_segments(segs, ecl)
 	
@@ -79,7 +80,8 @@ class QrCode(object):
 	def encode_binary(data, ecl):
 		"""Returns a QR Code symbol representing the given binary data string 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."""
+		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."""
 		if not isinstance(data, bytes):
 			raise TypeError("Binary array expected")
 		return QrCode.encode_segments([QrSegment.make_bytes(data)], ecl)
@@ -141,8 +143,8 @@ class QrCode(object):
 		"""This constructor can be called in one of two ways:
 		- 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
+		      and mask number. This is a cumbersome low-level constructor that should not be invoked directly by the user.
-		      to be even lower level than QrCode.encode_segments().
+		      To go one level up, see the QrCode.encode_segments() function.
 		- 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