Updated documentation comments for three QrSegment members, in all language versions.

c/qrcodegen.h

@@ -85,10 +85,9 @@ struct qrcodegen_Segment {
 	// The mode indicator for this segment.
 	enum qrcodegen_Mode mode;
 	
-	// The length of this segment's unencoded data. Always in the range [0, 32767].
+	// The length of this segment's unencoded data, measured in characters for
-	// For numeric, alphanumeric, and kanji modes, this measures in Unicode code points.
+	// numeric/alphanumeric/kanji mode, bytes for byte mode, and 0 for ECI mode.
-	// For byte mode, this measures in bytes (raw binary data, text in UTF-8, or other encodings).
+	// Always zero or positive.
-	// For ECI mode, this is always zero.
 	int numChars;
 	
 	// The data bits of this segment, packed in bitwise big endian.
@@ -97,6 +96,7 @@ struct qrcodegen_Segment {
 	
 	// The number of valid data bits used in the buffer. Requires
 	// 0 <= bitLength <= 32767, and bitLength <= (capacity of data array) * 8.
+	// The character count (numChars) must agree with the mode and the bit buffer length.
 	int bitLength;
 };
 

cpp/QrSegment.hpp

@@ -109,8 +109,8 @@ class QrSegment final {
 	
 	
 	/* 
-	 * Returns a list of zero or more segments to represent the given text string.
+	 * Returns a list of zero or more segments to represent the given text string. The result
-	 * The result may use various segment modes and switch modes to optimize the length of the bit stream.
+	 * may use various segment modes and switch modes to optimize the length of the bit stream.
 	 */
 	public: static std::vector<QrSegment> makeSegments(const char *text);
 	
@@ -142,7 +142,9 @@ class QrSegment final {
 	/* The mode indicator for this segment. */
 	private: Mode mode;
 	
-	/* The length of this segment's unencoded data, measured in characters. Always zero or positive. */
+	/* The length of this segment's unencoded data, measured in characters for
+	 * numeric/alphanumeric/kanji mode, bytes for byte mode, and 0 for ECI mode.
+	 * Always zero or positive. */
 	private: int numChars;
 	
 	/* The data bits of this segment. */
@@ -153,12 +155,16 @@ class QrSegment final {
 	
 	/* 
 	 * Creates a new QR Code segment with the given parameters and data.
+	 * The character count (numCh) must agree with the mode and the bit buffer length,
+	 * but the constraint isn't checked. The given bit buffer is copied and stored.
 	 */
 	public: QrSegment(Mode md, int numCh, const std::vector<bool> &dt);
 	
 	
 	/* 
 	 * Creates a new QR Code data segment with the given parameters and data.
+	 * The character count (numCh) must agree with the mode and the bit buffer length,
+	 * but the constraint isn't checked. The given bit buffer is moved and stored.
 	 */
 	public: QrSegment(Mode md, int numCh, std::vector<bool> &&dt);
 	

java/io/nayuki/qrcodegen/QrSegment.java

@@ -106,10 +106,10 @@ public final class QrSegment {
 	
 	
 	/**
-	 * Returns a new mutable list of zero or more segments to represent the specified Unicode text string.
+	 * Returns a list of zero or more segments to represent the specified Unicode text string.
 	 * The result may use various segment modes and switch modes to optimize the length of the bit stream.
 	 * @param text the text to be encoded, which can be any Unicode string
-	 * @return a list of segments containing the text
+	 * @return a new mutable list of segments containing the text
 	 * @throws NullPointerException if the text is {@code null}
 	 */
 	public static List<QrSegment> makeSegments(String text) {
@@ -159,7 +159,9 @@ public final class QrSegment {
 	/** The mode indicator for this segment. Never {@code null}. */
 	public final Mode mode;
 	
-	/** The length of this segment's unencoded data, measured in characters. Always zero or positive. */
+	/** The length of this segment's unencoded data, measured in characters for
+	 * numeric/alphanumeric/kanji mode, bytes for byte mode, and 0 for ECI mode.
+	 * Always zero or positive. */
 	public final int numChars;
 	
 	/** The data bits of this segment. Accessed through {@link getBits()}. Not {@code null}. */
@@ -170,8 +172,10 @@ public final class QrSegment {
 	
 	/**
 	 * Constructs a QR Code segment with the specified parameters and data.
+	 * The character count (numCh) must agree with the mode and the bit buffer length,
+	 * but the constraint isn't checked. The specified bit buffer is cloned and stored.
 	 * @param md the mode, which is not {@code null}
-	 * @param numCh the data length in characters, which is non-negative
+	 * @param numCh the data length in characters or bytes, which is non-negative
 	 * @param data the data bits of this segment, which is not {@code null}
 	 * @throws NullPointerException if the mode or data is {@code null}
 	 * @throws IllegalArgumentException if the character count is negative

javascript/qrcodegen.js

@@ -698,6 +698,9 @@ var qrcodegen = new function() {
 	 * 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.
+	 * This constructor creates a QR Code segment with the given parameters and data.
+	 * The character count (numChars) must agree with the mode and the bit buffer length,
+	 * but the constraint isn't checked. The given bit buffer is cloned and stored.
 	 */
 	this.QrSegment = function(mode, numChars, bitData) {
 		/*---- Constructor (low level) ----*/
@@ -708,7 +711,9 @@ var qrcodegen = new function() {
 		// The mode indicator for this segment.
 		Object.defineProperty(this, "mode", {value:mode});
 		
-		// The length of this segment's unencoded data, measured in characters. Always zero or positive.
+		// The length of this segment's unencoded data, measured in characters for
+		// numeric/alphanumeric/kanji mode, bytes for byte mode, and 0 for ECI mode.
+		// Always zero or positive.
 		Object.defineProperty(this, "numChars", {value:numChars});
 		
 		// Returns a copy of all bits, which is an array of 0s and 1s.

python/qrcodegen.py

@@ -678,11 +678,18 @@ class QrSegment(object):
 	# ---- Constructor (low level) ----
 	
 	def __init__(self, mode, numch, bitdata):
-		"""Creates a new QR Code segment with the given parameters and data."""
+		"""Creates a new QR Code segment with the given parameters and data.
+		The character count (numch) must agree with the mode and the bit buffer length,
+		but the constraint isn't checked. The given bit buffer is cloned and stored."""
 		if numch < 0 or not isinstance(mode, QrSegment.Mode):
 			raise ValueError()
 		self._mode = mode
+		
+		# The length of this segment's unencoded data, measured in characters for
+		# numeric/alphanumeric/kanji mode, bytes for byte mode, and 0 for ECI mode.
+		# Always zero or positive.
 		self._numchars = numch
+		
 		self._bitdata = list(bitdata)  # Make defensive copy
 	
 	

rust/src/lib.rs

@@ -832,7 +832,8 @@ pub struct QrSegment {
 	// The mode indicator for this segment.
 	mode: QrSegmentMode,
 	
-	// The length of this segment's unencoded data, measured in characters.
+	// The length of this segment's unencoded data, measured in characters for
+	// numeric/alphanumeric/kanji mode, bytes for byte mode, and 0 for ECI mode.
 	numchars: usize,
 	
 	// The bits of this segment.
@@ -905,8 +906,8 @@ impl QrSegment {
 	}
 	
 	
-	// Returns a new mutable list of zero or more segments to represent the given Unicode text string.
+	// Returns a list of zero or more segments to represent the given Unicode text string. The result
-	// The result may use various segment modes and switch modes to optimize the length of the bit stream.
+	// may use various segment modes and switch modes to optimize the length of the bit stream.
 	pub fn make_segments(text: &[char]) -> Vec<Self> {
 		if text.is_empty() {
 			vec![]
@@ -943,6 +944,8 @@ impl QrSegment {
 	/*---- Constructor (low level) ----*/
 	
 	// Creates a new QR Code segment with the given parameters and data.
+	// The character count (numchars) must agree with the mode and
+	// the bit buffer length, but the constraint isn't checked.
 	pub fn new(mode: QrSegmentMode, numchars: usize, data: Vec<bool>) -> Self {
 		Self {
 			mode: mode,

typescript/qrcodegen.ts

@@ -738,11 +738,15 @@ namespace qrcodegen {
 		/*-- Constructor (low level) and fields --*/
 		
 		// Creates a new QR Code segment with the given parameters and data.
+		// The character count (numChars) must agree with the mode and the bit buffer length,
+		// but the constraint isn't checked. The given bit buffer is cloned and stored.
 		public constructor(
 				// The mode indicator for this segment.
 				public readonly mode: QrSegment.Mode,
 				
-				// The length of this segment's unencoded data, measured in characters. Always zero or positive.
+				// The length of this segment's unencoded data, measured in characters for
+				// numeric/alphanumeric/kanji mode, bytes for byte mode, and 0 for ECI mode.
+				// Always zero or positive.
 				public readonly numChars: int,
 				
 				private readonly bitData: Array<bit>) {