Improve readability

Author: polldo

internal/lzss/lzss.go

@@ -24,17 +24,20 @@ import (
 )
 
 const (
-	idxsz  = 11 // Size of buffer indexes in bit, typically 10..13 bits
-	lensz  = 4  // Size of lookahead indexes in bit, typically 4..5 bits
-	charsz = 8  // Size of encoded chars in bit
+	idxsz = 11 // Size of buffer indexes in bits, typically 10..13 bits.
+	lensz = 4  // Size of lookahead indexes in bits, typically 4..5 bits.
 
-	threshold = 1                  // If match length <= threshold then output one character
-	bufsz     = (1 << idxsz)       // buffer size
-	looksz    = ((1 << lensz) + 1) // lookahead buffer size
-	historysz = bufsz - looksz     // history buffer size
+	charsz   = 8   // Size of encoded chars in bits.
+	bytemask = 128 // Mask with a bit in 8th position. Used to iterate through bits of a char.
 
-	charStartBit  = true  // Indicates next bits encode a char
-	tokenStartBit = false // Indicates next bits encode a token
+	threshold = 1 // If match length > threshold then output a token (idx, len), otherwise output one char.
+
+	bufsz     = (1 << idxsz)       // Buffer size.
+	looksz    = ((1 << lensz) + 1) // Lookahead buffer size.
+	historysz = bufsz - looksz     // History buffer size.
+
+	charStartBit  = true  // Indicates next bits encode a char.
+	tokenStartBit = false // Indicates next bits encode a token.
 )
 
 func min(x, y int) int {
@@ -44,6 +47,10 @@ func min(x, y int) int {
 	return y
 }
 
+// findLargestMatch looks for the largest sequence of characters (from current to current+ahead)
+// contained in the history of the buffer.
+// It returns the index of the found match, if any, and its length.
+// The index is relative to the current position. If idx 0 is returned than no match has been found.
 func findLargestMatch(buf []byte, current, size int) (idx, len int) {
 	idx = 0
 	len = 1
@@ -67,6 +74,8 @@ func findLargestMatch(buf []byte, current, size int) (idx, len int) {
 	return
 }
 
+// Encode takes a slice of bytes, compresses it using the lzss compression algorithm
+// and returns the result in a new bytes buffer.
 func Encode(data []byte) []byte {
 	// buffer is made up of two parts: the first is for already processed data (history); the second is for new data
 	buffer := make([]byte, bufsz*2)
@@ -104,6 +113,9 @@ func Encode(data []byte) []byte {
 	return out.bytes()
 }
 
+// filler abstracts the process of consuming an input buffer
+// using its bytes to fill another buffer.
+// It's been used to facilitate the handling of the input buffer in the Encode function.
 type filler struct {
 	src []byte
 	idx int
@@ -115,13 +127,21 @@ func newFiller(src []byte) *filler {
 	}
 }
 
+// fill tries to fill all the dst buffer with bytes read from src.
+// It returns the number of bytes moved from src to dst.
+// The src buffer offset is then incremented so that all the content of src
+// can be consumed in small chunks.
 func (f *filler) fill(dst []byte) int {
 	n := min(len(f.src)-f.idx, len(dst))
 	copy(dst, f.src[f.idx:f.idx+n])
 	f.idx += n
 	return n
 }
 
+// result is responsible for storing the actual result of the encoding.
+// It knows how to store characters and tokens in the resulting buffer.
+// It must be flushed at the end of the encoding in order to store the
+// remaining bits of bitBuffer.
 type result struct {
 	bitBuffer int
 	bitMask   int
@@ -131,11 +151,12 @@ type result struct {
 func newResult() *result {
 	return &result{
 		bitBuffer: 0,
-		bitMask:   128,
-		out:       bytes.NewBufferString(""),
+		bitMask:   bytemask,
+		out:       &bytes.Buffer{},
 	}
 }
 
+// addChar stores a char in the out buffer.
 func (r *result) addChar(c byte) {
 	i := int(c)
 	r.putbit(charStartBit)
@@ -145,6 +166,7 @@ func (r *result) addChar(c byte) {
 	}
 }
 
+// addToken stores a token in the out buffer.
 func (r *result) addToken(idx, len int) {
 	// Adjust idx and len to fit idxsz and lensz bits respectively
 	idx &= (bufsz - 1)
@@ -163,11 +185,13 @@ func (r *result) addToken(idx, len int) {
 }
 
 func (r *result) flush() {
-	if r.bitMask != 128 {
+	if r.bitMask != bytemask {
 		r.out.WriteByte(byte(r.bitBuffer))
 	}
 }
 
+// putbit puts the passed bit (true -> 1; false -> 0) in the bitBuffer.
+// When bitBuffer contains an entire byte it's written to the out buffer.
 func (r *result) putbit(b bool) {
 	if b {
 		r.bitBuffer |= r.bitMask
@@ -176,7 +200,7 @@ func (r *result) putbit(b bool) {
 	if r.bitMask == 0 {
 		r.out.WriteByte(byte(r.bitBuffer))
 		r.bitBuffer = 0
-		r.bitMask = 128
+		r.bitMask = bytemask
 	}
 }