More documentation for CineUnpacker-class (Practically done documenting now). Also changed parameter and return value types to a more uniform style (uint16 -> uint, int -> uint where applicable etc).

svn-id: r32688

2 files changed, 48 insertions, 18 deletions

diff --git a/engines/cine/unpack.cpp b/engines/cine/unpack.cpp
index a27387a1e3..6c14b1980b 100644
--- a/engines/cine/unpack.cpp
+++ b/engines/cine/unpack.cpp
@@ -40,8 +40,8 @@ uint32 CineUnpacker::readSource() {
 	return value;
 }
 
-int CineUnpacker::rcr(int inputCarry) {
-	int outputCarry = (_chunk32b & 1);
+uint CineUnpacker::rcr(bool inputCarry) {
+	uint outputCarry = (_chunk32b & 1);
 	_chunk32b >>= 1;
 	if (inputCarry) {
 		_chunk32b |= 0x80000000;
@@ -49,20 +49,20 @@ int CineUnpacker::rcr(int inputCarry) {
 	return outputCarry;
 }
 
-int CineUnpacker::nextBit() {
-	int carry = rcr(0);
+uint CineUnpacker::nextBit() {
+	uint carry = rcr(false);
 	// Normally if the chunk becomes zero then the carry is one as
 	// the end of chunk marker is always the last to be shifted out.
 	if (_chunk32b == 0) {
 		_chunk32b = readSource();
 		_crc ^= _chunk32b;
-		carry = rcr(1); // Put the end of chunk marker in the most significant bit
+		carry = rcr(true); // Put the end of chunk marker in the most significant bit
 	}
 	return carry;
 }
 
-uint16 CineUnpacker::getBits(byte numBits) {
-	uint16 c = 0;
+uint CineUnpacker::getBits(uint numBits) {
+	uint c = 0;
 	while (numBits--) {
 		c <<= 1;
 		c |= nextBit();
@@ -70,7 +70,7 @@ uint16 CineUnpacker::getBits(byte numBits) {
 	return c;
 }
 
-void CineUnpacker::unpackRawBytes(uint16 numBytes) {
+void CineUnpacker::unpackRawBytes(uint numBytes) {
 	if (_dst >= _dstEnd || _dst - numBytes + 1 < _dstBegin) {
 		_error = true;
 		return; // Destination pointer is out of bounds for this operation
@@ -81,7 +81,7 @@ void CineUnpacker::unpackRawBytes(uint16 numBytes) {
 	}
 }
 
-void CineUnpacker::copyRelocatedBytes(uint16 offset, uint16 numBytes) {
+void CineUnpacker::copyRelocatedBytes(uint offset, uint numBytes) {
 	if (_dst + offset >= _dstEnd || _dst - numBytes + 1 < _dstBegin) {
 		_error = true;
 		return; // Destination pointer is out of bounds for this operation
diff --git a/engines/cine/unpack.h b/engines/cine/unpack.h
index 5bb7bfc8f9..e16cb594a9 100644
--- a/engines/cine/unpack.h
+++ b/engines/cine/unpack.h
@@ -39,38 +39,68 @@ namespace Cine {
  */
 class CineUnpacker {
 public:
-	/** Returns true if unpacking was successful, otherwise false. */
+	/**
+	 * Unpacks packed data from the source buffer to the destination buffer.
+	 * @warning Do NOT call this on data that is not packed.
+	 * @note Source and destination buffer pointers can be the same as long as there's space for the unpacked data.
+	 * @param src Pointer to the source buffer.
+	 * @param srcLen Length of the source buffer.
+	 * @param dst Pointer to the destination buffer.
+	 * @param dstLen Length of the destination buffer.
+	 * @return True if no errors were detected in the source data and unpacking was successful, otherwise false.
+	 */
 	bool unpack(const byte *src, uint srcLen, byte *dst, uint dstLen);
 private:
-	/** Reads a single big endian 32-bit integer from the source and goes backwards 4 bytes. */
+	/**
+	 * Reads an unsigned big endian 32-bit integer from the source stream and goes backwards 4 bytes.
+	 * @return If the operation is valid, an unsigned big endian 32-bit integer read from the source stream.
+	 * @return If the operation is invalid, zero.
+	 * @note Sets internal error state if the read operation would be out of source bounds.
+	 */
 	uint32 readSource();
 
 	/**
 	 * Shifts the current internal 32-bit chunk to the right by one.
 	 * Puts input carry into internal chunk's topmost (i.e. leftmost) bit.
-	 * Returns the least significant bit that was shifted out.
+	 * @return The least significant bit that was shifted out from the chunk.
+	 */
+	uint rcr(bool inputCarry);
+
+	/**
+	 * Get the next bit from the source stream.
+	 * @note Changes the bit position in the source stream.
+	 * @return The next bit from the source stream.
+	 */
+	uint nextBit();
+
+	/**
+	 * Get bits from the source stream.
+	 * @note Changes the bit position in the source stream.
+	 * @param numBits Number of bits to read from the source stream.	 
+	 * @return Integer value consisting of the bits read from the source stream (In range [0, (2 ** numBits) - 1]).
+	 * @return Later the bit was read from the source, the less significant it is in the return value.
 	 */
-	int rcr(int inputCarry);
-	int nextBit();
-	uint16 getBits(byte numBits);
+	uint getBits(uint numBits);
 
 	/**
 	 * Copy raw bytes from the input stream and write them to the destination stream.
 	 * This is used when no adequately long match is found in the sliding window.
+	 * @note Sets internal error state if the operation would be out of bounds.
 	 * @param numBytes Amount of bytes to copy from the input stream
 	 */
-	void unpackRawBytes(uint16 numBytes);
+	void unpackRawBytes(uint numBytes);
 
 	/**
 	 * Copy bytes from the sliding window in the destination buffer.
 	 * This is used when a match of two bytes or longer is found.
+	 * @note Sets internal error state if the operation would be out of bounds.
 	 * @param offset Offset in the sliding window
 	 * @param numBytes Amount of bytes to copy
 	 */
-	void copyRelocatedBytes(uint16 offset, uint16 numBytes);
+	void copyRelocatedBytes(uint offset, uint numBytes);
 private:
 	uint32 _crc;      //!< Error-detecting code (This should be zero after successful unpacking)
-	uint32 _chunk32b; //!< The current internal 32-bit chunk
+	uint32 _chunk32b; //!< The current internal 32-bit chunk of source data
 	byte *_dst;       //!< Pointer to the current position in the destination buffer
 	const byte *_src; //!< Pointer to the current position in the source buffer