Updated and synchronized documentation comments for QrSegment class's {top-level, constructor, makeBytes()}, in all languages.

c/qrcodegen.h

@@ -80,8 +80,15 @@ enum qrcodegen_Mode {
 
 
 /* 
- * 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.
+ * A segment of character/binary/control data in a QR Code symbol.
+ * The mid-level way to create a segment is to take the payload data
+ * and call a factory function such as qrcodegen_makeNumeric().
+ * The low-level way to create a segment is to custom-make the bit buffer
+ * and initialize a qrcodegen_Segment struct with appropriate values.
+ * 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.
+ * Moreover, the maximum allowed bit length is 32767 because
+ * the largest QR Code (version 40) has 31329 modules.
  */
 struct qrcodegen_Segment {
 	// The mode indicator of this segment.
@@ -200,7 +207,9 @@ size_t qrcodegen_calcSegmentBufferSize(enum qrcodegen_Mode mode, size_t numChars
 
 
 /* 
- * Returns a segment representing the given binary data encoded in byte mode.
+ * Returns a segment representing the given binary data encoded in
+ * byte mode. All input byte arrays are acceptable. Any text string
+ * can be converted to UTF-8 bytes and encoded as a byte mode segment.
  */
 struct qrcodegen_Segment qrcodegen_makeBytes(const uint8_t data[], size_t len, uint8_t buf[]);
 

cpp/QrSegment.hpp

@@ -31,8 +31,12 @@
 namespace qrcodegen {
 
 /* 
- * 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.
+ * A segment of character/binary/control data in a QR Code symbol.
+ * Instances of this class are immutable.
+ * The mid-level way to create a segment is to take the payload data
+ * and call a static factory function such as QrSegment::makeNumeric().
+ * The low-level way to create a segment is to custom-make the bit buffer
+ * and call the QrSegment() constructor with appropriate values.
  * 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.
@@ -89,7 +93,9 @@ class QrSegment final {
 	/*---- Static factory functions (mid level) ----*/
 	
 	/* 
-	 * Returns a segment representing the given binary data encoded in byte mode.
+	 * Returns a segment representing the given binary data encoded in
+	 * byte mode. All input byte vectors are acceptable. Any text string
+	 * can be converted to UTF-8 bytes and encoded as a byte mode segment.
 	 */
 	public: static QrSegment makeBytes(const std::vector<std::uint8_t> &data);
 	
@@ -158,7 +164,7 @@ class QrSegment final {
 	/*---- Constructors (low level) ----*/
 	
 	/* 
-	 * Creates a new QR Code segment with the given parameters and data.
+	 * Creates a new QR Code segment with the given attributes 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.
 	 */

java/io/nayuki/qrcodegen/QrSegment.java

@@ -31,18 +31,27 @@ import java.util.regex.Pattern;
 
 
 /**
- * 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.
+ * A segment of character/binary/control data in a QR Code symbol.
+ * Instances of this class are immutable.
+ * <p>The mid-level way to create a segment is to take the payload data and call a
+ * static factory function such as {@link QrSegment#makeNumeric(String)}. The low-level
+ * way to create a segment is to custom-make the bit buffer and call the {@link
+ * QrSegment#QrSegment(Mode,int,BitBuffer) constructor} with appropriate values.</p>
  * <p>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.</p>
+ * Any segment longer than this is meaningless for the purpose of generating QR Codes.
+ * This class can represent kanji mode segments, but provides no help in encoding them
+ * - see {@link QrSegmentAdvanced} for full kanji support.</p>
  */
 public final class QrSegment {
 	
 	/*---- Static factory functions (mid level) ----*/
 	
 	/**
-	 * Returns a segment representing the specified binary data encoded in byte mode.
+	 * Returns a segment representing the specified binary data
+	 * encoded in byte mode. All input byte arrays are acceptable.
+	 * <p>Any text string can be converted to UTF-8 bytes ({@code
+	 * s.getBytes(StandardCharsets.UTF_8)}) and encoded as a byte mode segment.</p>
 	 * @param data the binary data
 	 * @return a segment containing the data
 	 * @throws NullPointerException if the array is {@code null}
@@ -171,7 +180,7 @@ public final class QrSegment {
 	/*---- Constructor (low level) ----*/
 	
 	/**
-	 * Constructs a QR Code segment with the specified parameters and data.
+	 * Constructs a QR Code segment with the specified attributes 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}

javascript/qrcodegen.js

@@ -695,12 +695,16 @@ var qrcodegen = new function() {
 	/*---- Data segment class ----*/
 	
 	/* 
-	 * 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.
+	 * A segment of character/binary/control data in a QR Code symbol.
+	 * Instances of this class are immutable.
+	 * The mid-level way to create a segment is to take the payload data
+	 * and call a static factory function such as QrSegment.makeNumeric().
+	 * The low-level way to create a segment is to custom-make the bit buffer
+	 * and call the QrSegment() constructor with appropriate values.
 	 * 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.
+	 * This constructor creates a QR Code segment with the given attributes 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.
 	 */
@@ -728,7 +732,9 @@ var qrcodegen = new function() {
 	/*---- Static factory functions (mid level) 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. All input byte arrays are acceptable. Any text string
+	 * can be converted to UTF-8 bytes and encoded as a byte mode segment.
 	 */
 	this.QrSegment.makeBytes = function(data) {
 		var bb = new BitBuffer();

python/qrcodegen.py

@@ -586,8 +586,12 @@ class QrCode(object):
 # ---- Data segment class ----
 
 class QrSegment(object):
-	"""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.
+	"""A segment of character/binary/control data in a QR Code symbol.
+	Instances of this class are immutable.
+	The mid-level way to create a segment is to take the payload data
+	and call a static factory function such as QrSegment.make_numeric().
+	The low-level way to create a segment is to custom-make the bit buffer
+	and call the QrSegment() constructor with appropriate values.
 	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."""
@@ -596,7 +600,9 @@ class QrSegment(object):
 	
 	@staticmethod
 	def make_bytes(data):
-		"""Returns a segment representing the given binary data encoded in byte mode."""
+		"""Returns a segment representing the given binary data encoded in byte mode.
+		All input byte lists are acceptable. Any text string can be converted to
+		UTF-8 bytes (s.encode("UTF-8")) and encoded as a byte mode segment."""
 		py3 = sys.version_info.major >= 3
 		if (py3 and isinstance(data, str)) or (not py3 and isinstance(data, unicode)):
 			raise TypeError("Byte string/list expected")
@@ -680,7 +686,7 @@ 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 attributes 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 not isinstance(mode, QrSegment.Mode):

rust/src/lib.rs

@@ -828,8 +828,17 @@ impl ReedSolomonGenerator {
 
 /*---- QrSegment functionality ----*/
 
-// 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.
+/* 
+ * A segment of character/binary/control data in a QR Code symbol.
+ * Instances of this struct are immutable.
+ * The mid-level way to create a segment is to take the payload data
+ * and call a static factory function such as QrSegment::make_numeric().
+ * The low-level way to create a segment is to custom-make the bit buffer
+ * and call the QrSegment::new() constructor with appropriate values.
+ * This segment struct 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.
+ */
 #[derive(Clone)]
 pub struct QrSegment {
 	
@@ -851,7 +860,9 @@ impl QrSegment {
 	
 	/*---- Static factory functions (mid level) ----*/
 	
-	// Returns a segment representing the given binary data encoded in byte mode.
+	// Returns a segment representing the given binary data encoded in
+	// byte mode. All input byte slices are acceptable. Any text string
+	// can be converted to UTF-8 bytes and encoded as a byte mode segment.
 	pub fn make_bytes(data: &[u8]) -> Self {
 		let mut bb = BitBuffer(Vec::with_capacity(data.len() * 8));
 		for b in data {
@@ -948,7 +959,7 @@ impl QrSegment {
 	
 	/*---- Constructor (low level) ----*/
 	
-	// Creates a new QR Code segment with the given parameters and data.
+	// Creates a new QR Code segment with the given attributes 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 {

typescript/qrcodegen.ts

@@ -649,8 +649,12 @@ namespace qrcodegen {
 	/*---- Data segment class ----*/
 	
 	/* 
-	 * 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.
+	 * A segment of character/binary/control data in a QR Code symbol.
+	 * Instances of this class are immutable.
+	 * The mid-level way to create a segment is to take the payload data
+	 * and call a static factory function such as QrSegment.makeNumeric().
+	 * The low-level way to create a segment is to custom-make the bit buffer
+	 * and call the QrSegment() constructor with appropriate values.
 	 * 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.
@@ -659,7 +663,9 @@ namespace qrcodegen {
 		
 		/*-- Static factory functions (mid level) --*/
 		
-		// Returns a segment representing the given binary data encoded in byte mode.
+		// Returns a segment representing the given binary data encoded in
+		// byte mode. All input byte arrays are acceptable. Any text string
+		// can be converted to UTF-8 bytes and encoded as a byte mode segment.
 		public static makeBytes(data: Array<byte>): QrSegment {
 			let bb = new BitBuffer();
 			for (let b of data)
@@ -738,7 +744,7 @@ namespace qrcodegen {
 		
 		/*-- Constructor (low level) and fields --*/
 		
-		// Creates a new QR Code segment with the given parameters and data.
+		// Creates a new QR Code segment with the given attributes 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(