Converted Java BitBuffer comments to Javadoc, updated related comments in most other language versions.

cpp/BitBuffer.hpp

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

java/io/nayuki/qrcodegen/BitBuffer.java

@@ -28,20 +28,23 @@ import java.util.Objects;
 
 
 /**
- * An appendable sequence of bits. Bits are packed in big endian within a byte.
+ * An appendable sequence of bits (0's and 1's).
  */
 public final class BitBuffer implements Cloneable {
 	
 	/*---- Fields ----*/
 	
 	private BitSet data;
+	
 	private int bitLength;
 	
 	
 	
 	/*---- Constructor ----*/
 	
-	// Creates an empty bit buffer (length 0).
+	/**
+	 * Constructs an empty bit buffer (length 0).
+	 */
 	public BitBuffer() {
 		data = new BitSet();
 		bitLength = 0;
@@ -51,13 +54,21 @@ public final class BitBuffer implements Cloneable {
 	
 	/*---- Methods ----*/
 	
-	// Returns the number of bits in the buffer, which is a non-negative value.
+	/**
+	 * Returns the length of this sequence, which is a non-negative value.
+	 * @return the length of this sequence
+	 */
 	public int bitLength() {
 		return bitLength;
 	}
 	
 	
-	// Returns the bit at the given index, yielding 0 or 1, or throwing IndexOutOfBoundsException.
+	/**
+	 * Returns the bit at the specified index, yielding 0 or 1.
+	 * @param index the index to get the bit at
+	 * @return the bit at the specified index
+	 * @throws IndexOutOfBoundsException if index < 0 or index ≥ bitLength
+	 */
 	public int getBit(int index) {
 		if (index < 0 || index >= bitLength)
 			throw new IndexOutOfBoundsException();
@@ -65,7 +76,11 @@ public final class BitBuffer implements Cloneable {
 	}
 	
 	
-	// Returns a copy of all bytes, padding up to the nearest byte. Bits are packed in big endian within a byte.
+	/**
+	 * 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})
+	 */
 	public byte[] getBytes() {
 		byte[] result = new byte[(bitLength + 7) / 8];
 		for (int i = 0; i < bitLength; i++)
@@ -74,8 +89,12 @@ public final class BitBuffer implements Cloneable {
 	}
 	
 	
-	// Appends the given number of bits of the given value to this sequence.
+	/**
-	// If 0 <= len <= 31, then this requires 0 <= val < 2^len.
+	 * Appends the specified number of low bits of the specified value
+	 * to this sequence. Requires 0 &le; val &lt; 2<sup>len</sup>.
+	 * @param val the value to append
+	 * @param len the number of low bits in the value to take
+	 */
 	public void appendBits(int val, int len) {
 		if (len < 0 || len > 31 || val >>> len != 0)
 			throw new IllegalArgumentException("Value out of range");
@@ -84,7 +103,11 @@ public final class BitBuffer implements Cloneable {
 	}
 	
 	
-	// Appends the data of the given segment to this bit buffer.
+	/**
+	 * Appends the bit data of the specified segment to this bit buffer.
+	 * @param seg the segment whose data to append (not {@code null})
+	 * @throws NullPointerException if the segment is {@code null}
+	 */
 	public void appendData(QrSegment seg) {
 		Objects.requireNonNull(seg);
 		BitBuffer bb = seg.data;
@@ -93,7 +116,10 @@ public final class BitBuffer implements Cloneable {
 	}
 	
 	
-	// Returns a copy of this bit buffer object.
+	/**
+	 * Returns a copy of this bit buffer object.
+	 * @return a copy of this bit buffer object
+	 */
 	public BitBuffer clone() {
 		try {
 			BitBuffer result = (BitBuffer)super.clone();

javascript/qrcodegen.js

@@ -736,7 +736,7 @@ var qrcodegen = new function() {
 	this.QrSegment = function(mode, numChars, bitData) {
 		if (numChars < 0 || !(mode instanceof Mode))
 			throw "Invalid argument";
-		bitData = bitData.slice();
+		bitData = bitData.slice();  // Make defensive copy
 		
 		// The mode indicator for this segment.
 		Object.defineProperty(this, "mode", {value:mode});
@@ -746,7 +746,7 @@ var qrcodegen = new function() {
 		
 		// Returns a copy of all bits, which is an array of 0s and 1s.
 		this.getBits = function() {
-			return bitData.slice();
+			return bitData.slice();  // Make defensive copy
 		};
 	};
 	
@@ -992,7 +992,8 @@ var qrcodegen = new function() {
 	 */
 	function BitBuffer() {
 		
-		// Returns a copy of all bytes, padding up to the nearest byte.
+		// Packs this buffer's bits into bytes in big endian,
+		// padding with '0' bit values, and returns the new array.
 		this.getBytes = function() {
 			var result = [];
 			while (result.length * 8 < this.length)
@@ -1003,8 +1004,8 @@ var qrcodegen = new function() {
 			return result;
 		};
 		
-		// Appends the given number of bits of the given value to this sequence.
+		// Appends the given number of low bits of the given value
-		// If 0 <= len <= 31, then this requires 0 <= val < 2^len.
+		// to this sequence. Requires 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

@@ -696,7 +696,7 @@ class QrSegment(object):
 			raise ValueError()
 		self._mode = mode
 		self._numchars = numch
-		self._bitdata = list(bitdata)  # Defensive copy
+		self._bitdata = list(bitdata)  # Make defensive copy
 	
 	
 	# ---- Accessor methods ----
@@ -708,7 +708,7 @@ class QrSegment(object):
 		return self._numchars
 	
 	def get_bits(self):
-		return list(self._bitdata)  # Defensive copy
+		return list(self._bitdata)  # Make defensive copy
 	
 	
 	# Package-private helper function.
@@ -833,14 +833,16 @@ class _BitBuffer(list):
 	"""An appendable sequence of bits (0's and 1's)."""
 	
 	def get_bytes(self):
-		"""Returns a copy of all bytes, padding up to the nearest byte. Bits are packed in big endian within a byte."""
+		"""Packs this buffer's bits into bytes in big endian,
+		padding with '0' bit values, and returns the new list."""
 		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 bits of the given value to this sequence. This requires 0 <= val < 2^n."""
+		"""Appends the given number of low bits of the given value
+		to this sequence. Requires 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)))