Updated class BitBuffer's documentation comments, in all languages.

c/qrcodegen.c

@@ -176,8 +176,8 @@ bool qrcodegen_encodeBinary(uint8_t dataAndTemp[], size_t dataLen, uint8_t qrcod
 }
 
 
-// Appends the given sequence of bits to the given byte-based bit buffer, increasing the bit length.
-// Requires 0 <= numBits <= 16 and 0 <= val < 2^numBits.
+// Appends the given number of low-order bits of the given value to the given byte-based
+// bit buffer, increasing the bit length. Requires 0 <= numBits <= 16 and val < 2^numBits.
 testable void appendBitsToBuffer(unsigned int val, int numBits, uint8_t buffer[], int *bitLen) {
 	assert(0 <= numBits && numBits <= 16 && (unsigned long)val >> numBits == 0);
 	for (int i = numBits - 1; i >= 0; i--, (*bitLen)++)

cpp/BitBuffer.hpp

@@ -30,7 +30,7 @@
 namespace qrcodegen {
 
 /* 
- * An appendable sequence of bits (0s and 1s).
+ * An appendable sequence of bits (0s and 1s). Mainly used by QrSegment.
  */
 class BitBuffer final : public std::vector<bool> {
 	
@@ -43,13 +43,13 @@ class BitBuffer final : public std::vector<bool> {
 	
 	/*---- Methods ----*/
 	
-	// Packs this buffer's bits into bytes in big endian,
-	// padding with '0' bit values, and returns the new vector.
+	// Returns a vector representing this buffer's bits packed into bytes in big endian. If the
+	// bit length isn't a multiple of 8, then the remaining bits of the final byte are all '0'.
 	public: std::vector<std::uint8_t> getBytes() const;
 	
 	
-	// Appends the given number of low bits of the given value to
-	// this sequence. Requires 0 <= len <= 31 and 0 <= val < 2^len.
+	// Appends the given number of low-order bits of the given value
+	// to this buffer. Requires 0 <= len <= 31 and val < 2^len.
 	public: void appendBits(std::uint32_t val, int len);
 	
 };

java/io/nayuki/qrcodegen/BitBuffer.java

@@ -28,7 +28,7 @@ import java.util.Objects;
 
 
 /**
- * An appendable sequence of bits (0s and 1s).
+ * An appendable sequence of bits (0s and 1s). Mainly used by {@link QrSegment}.
  */
 public final class BitBuffer implements Cloneable {
 	
@@ -78,9 +78,9 @@ public final class BitBuffer implements Cloneable {
 	
 	
 	/**
-	 * Packs this buffer's bits into bytes in big endian,
-	 * padding with '0' bit values, and returns the new array.
-	 * @return this sequence as a new array of bytes (not {@code null})
+	 * Returns an array representing this buffer's bits packed into bytes in big endian. If the
+	 * bit length isn't a multiple of 8, then the remaining bits of the final byte are all '0'.
+	 * @return a new byte array (not {@code null}) representing this bit sequence
 	 */
 	public byte[] getBytes() {
 		byte[] result = new byte[(bitLength + 7) >>> 3];  // Round up to whole byte, won't overflow
@@ -93,10 +93,10 @@ public final class BitBuffer implements Cloneable {
 	
 	
 	/**
-	 * Appends the specified number of low bits of the specified value to this
-	 * sequence. Requires 0 &#x2264; len &#x2264; 31 and 0 &#x2264; val &lt; 2<sup>len</sup>.
+	 * Appends the specified number of low-order bits of the specified value to this
+	 * buffer. Requires 0 &#x2264; len &#x2264; 31 and 0 &#x2264; val &lt; 2<sup>len</sup>.
 	 * @param val the value to append
-	 * @param len the number of low bits in the value to take
+	 * @param len the number of low-order bits in the value to take
 	 * @throws IllegalArgumentException if the value or number of bits is out of range
 	 * @throws IllegalStateException if appending the data
 	 * would make bitLength exceed Integer.MAX_VALUE
@@ -112,7 +112,7 @@ public final class BitBuffer implements Cloneable {
 	
 	
 	/**
-	 * Appends the specified bit buffer to this bit buffer.
+	 * Appends the content of the specified bit buffer to this buffer.
 	 * @param bb the bit buffer whose data to append (not {@code null})
 	 * @throws NullPointerException if the bit buffer is {@code null}
 	 * @throws IllegalStateException if appending the data
@@ -128,8 +128,8 @@ public final class BitBuffer implements Cloneable {
 	
 	
 	/**
-	 * Returns a copy of this bit buffer object.
-	 * @return a copy of this bit buffer object
+	 * Returns a new copy of this buffer.
+	 * @return a new copy of this buffer (not {@code null})
 	 */
 	public BitBuffer clone() {
 		try {

javascript/qrcodegen.js

@@ -962,13 +962,13 @@ var qrcodegen = new function() {
 	
 	/* 
 	 * A private helper class that represents an appendable sequence of bits (0s and 1s).
-	 * This constructor creates an empty bit buffer (length 0).
+	 * Mainly used by QrSegment. This constructor creates an empty bit buffer (length 0).
 	 */
 	function BitBuffer() {
 		Array.call(this);
 		
-		// Packs this buffer's bits into bytes in big endian,
-		// padding with '0' bit values, and returns the new array.
+		// Returns a new array representing this buffer's bits packed into bytes in big endian. If the
+		// bit length isn't a multiple of 8, then the remaining bits of the final byte are all '0'.
 		this.getBytes = function() {
 			var result = [];
 			while (result.length * 8 < this.length)
@@ -979,8 +979,8 @@ var qrcodegen = new function() {
 			return result;
 		};
 		
-		// Appends the given number of low bits of the given value to
-		// this sequence. Requires 0 <= len <= 31 and 0 <= val < 2^len.
+		// Appends the given number of low-order bits of the given value
+		// to this buffer. Requires 0 <= len <= 31 and 0 <= val < 2^len.
 		this.appendBits = function(val, len) {
 			if (len < 0 || len > 31 || val >>> len != 0)
 				throw "Value out of range";

python/qrcodegen.py

@@ -829,19 +829,19 @@ class _ReedSolomonGenerator(object):
 
 
 class _BitBuffer(list):
-	"""An appendable sequence of bits (0s and 1s)."""
+	"""An appendable sequence of bits (0s and 1s). Mainly used by QrSegment."""
 	
 	def get_bytes(self):
-		"""Packs this buffer's bits into bytes in big endian,
-		padding with '0' bit values, and returns the new list."""
+		"""Returns a new list representing this buffer's bits packed into bytes in big endian. If the
+		bit length isn't a multiple of 8, then the remaining bits of the final byte are all '0'."""
 		result = [0] * ((len(self) + 7) // 8)
 		for (i, bit) in enumerate(self):
 			result[i >> 3] |= bit << (7 - (i & 7))
 		return result
 	
 	def append_bits(self, val, n):
-		"""Appends the given number of low bits of the given value
-		to this sequence. Requires n >= 0 and 0 <= val < 2^n."""
+		"""Appends the given number of low-order bits of the given
+		value to this buffer. Requires n >= 0 and 0 <= val < 2^n."""
 		if n < 0 or val >> n != 0:
 			raise ValueError("Value out of range")
 		self.extend(((val >> i) & 1) for i in reversed(range(n)))

rust/src/lib.rs

@@ -1070,13 +1070,13 @@ impl QrSegmentMode {
 
 /*---- Bit buffer functionality ----*/
 
-// An appendable sequence of bits (0s and 1s).
+// An appendable sequence of bits (0s and 1s). Mainly used by QrSegment.
 pub struct BitBuffer(pub Vec<bool>);
 
 
 impl BitBuffer {
-	// Appends the given number of low bits of the given value
-	// to this sequence. Requires len <= 31 and 0 <= val < 2^len.
+	// Appends the given number of low-order bits of the given value
+	// to this buffer. Requires len <= 31 and val < 2^len.
 	pub fn append_bits(&mut self, val: u32, len: u8) {
 		assert!(len <= 31 && (val >> len) == 0, "Value out of range");
 		self.0.extend((0 .. len as i32).rev().map(|i| get_bit(val, i)));  // Append bit by bit

typescript/qrcodegen.ts

@@ -890,12 +890,13 @@ namespace qrcodegen {
 	
 	
 	/* 
-	 * An appendable sequence of bits (0s and 1s). The implicit constructor creates an empty bit buffer (length 0).
+	 * An appendable sequence of bits (0s and 1s). Mainly used by QrSegment.
+	 * The implicit constructor creates an empty bit buffer (length 0).
 	 */
 	class BitBuffer extends Array<bit> {
 		
-		// Packs this buffer's bits into bytes in big endian,
-		// padding with '0' bit values, and returns the new array.
+		// Returns a new array representing this buffer's bits packed into bytes in big endian. If the
+		// bit length isn't a multiple of 8, then the remaining bits of the final byte are all '0'.
 		public getBytes(): Array<byte> {
 			let result: Array<byte> = [];
 			while (result.length * 8 < this.length)
@@ -906,8 +907,8 @@ namespace qrcodegen {
 		}
 		
 		
-		// Appends the given number of low bits of the given value to
-		// this sequence. Requires 0 <= len <= 31 and 0 <= val < 2^len.
+		// Appends the given number of low-order bits of the given value
+		// to this buffer. Requires 0 <= len <= 31 and 0 <= val < 2^len.
 		public appendBits(val: int, len: int): void {
 			if (len < 0 || len > 31 || val >>> len != 0)
 				throw "Value out of range";