bitio,doc: Even more cleanup

pkg/bitio/bitio.go

@@ -8,40 +8,43 @@ import (
 	"strings"
 )
 
+// ErrOffset means seek positions is invalid
 var ErrOffset = errors.New("invalid seek offset")
+
+// ErrNegativeNBits means read tried to read negative number of bits
 var ErrNegativeNBits = errors.New("negative number of bits")
 
-// Reader is something that reads bits
-// Similar to io.Reader
+// Reader is something that reads bits.
+// Similar to io.Reader.
 type Reader interface {
 	ReadBits(p []byte, nBits int64) (n int64, err error)
 }
 
-// Writer is something that writs bits
-// Similar to io.Writer
+// Writer is something that writs bits.
+// Similar to io.Writer.
 type Writer interface {
 	WriteBits(p []byte, nBits int64) (n int64, err error)
 }
 
 // Seeker is something that seeks bits
-// Similar to io.Seeker
+// Similar to io.Seeker.
 type Seeker interface {
 	SeekBits(bitOffset int64, whence int) (int64, error)
 }
 
-// ReaderAt is something that reads bits at an offset
-// Similar to io.ReaderAt
+// ReaderAt is something that reads bits at an offset.
+// Similar to io.ReaderAt.
 type ReaderAt interface {
 	ReadBitsAt(p []byte, nBits int64, bitOff int64) (n int64, err error)
 }
 
-// ReadSeeker is bitio.Reader and bitio.Seeker
+// ReadSeeker is bitio.Reader and bitio.Seeker.
 type ReadSeeker interface {
 	Reader
 	Seeker
 }
 
-// ReadAtSeeker is bitio.ReaderAt and bitio.Seeker
+// ReadAtSeeker is bitio.ReaderAt and bitio.Seeker.
 type ReadAtSeeker interface {
 	ReaderAt
 	Seeker
@@ -54,9 +57,9 @@ type ReaderAtSeeker interface {
 	Seeker
 }
 
-// NewBitReader reader reading nBits bits from a []byte
+// NewBitReader reader reading nBits bits from a []byte.
 // If nBits is -1 all bits will be used.
-// Similar to bytes.NewReader
+// Similar to bytes.NewReader.
 func NewBitReader(buf []byte, nBits int64) *SectionReader {
 	if nBits < 0 {
 		nBits = int64(len(buf)) * 8
@@ -68,7 +71,7 @@ func NewBitReader(buf []byte, nBits int64) *SectionReader {
 	)
 }
 
-// BitsByteCount returns smallest amount of bytes to fit nBits bits
+// BitsByteCount returns smallest amount of bytes to fit nBits bits.
 func BitsByteCount(nBits int64) int64 {
 	n := nBits / 8
 	if nBits%8 != 0 {
@@ -77,7 +80,7 @@ func BitsByteCount(nBits int64) int64 {
 	return n
 }
 
-// BytesFromBitString []byte from bit string, ex: "0101" -> ([]byte{0x50}, 4)
+// BytesFromBitString from []byte to bit string, ex: "0101" -> ([]byte{0x50}, 4)
 func BytesFromBitString(s string) ([]byte, int64) {
 	r := len(s) % 8
 	bufLen := len(s) / 8
@@ -97,7 +100,7 @@ func BytesFromBitString(s string) ([]byte, int64) {
 	return buf, int64(len(s))
 }
 
-// BitStringFromBytes string from []byte], ex: ([]byte{0x50}, 4) -> "0101"
+// BitStringFromBytes from string to []byte, ex: ([]byte{0x50}, 4) -> "0101"
 func BitStringFromBytes(buf []byte, nBits int64) string {
 	sb := &strings.Builder{}
 	for i := int64(0); i < nBits; i++ {
@@ -110,8 +113,8 @@ func BitStringFromBytes(buf []byte, nBits int64) string {
 	return sb.String()
 }
 
-// CopyBuffer bits from src to dst using provided byte buffer
-// Similar to io.CopyBuffer
+// CopyBuffer bits from src to dst using provided byte buffer.
+// Similar to io.CopyBuffer.
 func CopyBuffer(dst Writer, src Reader, buf []byte) (n int64, err error) {
 	// same default size as io.Copy
 	if buf == nil {
@@ -144,8 +147,8 @@ func CopyBuffer(dst Writer, src Reader, buf []byte) (n int64, err error) {
 	return written, err
 }
 
-// Copy bits from src to dst
-// Similar to io.Copy
+// Copy bits from src to dst.
+// Similar to io.Copy.
 func Copy(dst Writer, src Reader) (n int64, err error) {
 	return CopyBuffer(dst, src, nil)
 }
@@ -214,12 +217,16 @@ func readFull(p []byte, nBits int64, bitOff int64, fn func(p []byte, nBits int64
 	return nBits, nil
 }
 
+// ReadAtFull expects to read nBits from r at bitOff.
+// Similar to io.ReadFull.
 func ReadAtFull(r ReaderAt, p []byte, nBits int64, bitOff int64) (int64, error) {
 	return readFull(p, nBits, bitOff, func(p []byte, nBits int64, bitOff int64) (int64, error) {
 		return r.ReadBitsAt(p, nBits, bitOff)
 	})
 }
 
+// ReadFull expects to read nBits from r.
+// Similar to io.ReadFull.
 func ReadFull(r Reader, p []byte, nBits int64) (int64, error) {
 	return readFull(p, nBits, 0, func(p []byte, nBits int64, bitOff int64) (int64, error) {
 		return r.ReadBits(p, nBits)

pkg/bitio/buffer.go

@@ -6,8 +6,8 @@ import (
 	"io"
 )
 
-// Buffer is a bitio.Reader and bitio.Writer providing a bit buffer
-// Similar to bytes.Buffer
+// Buffer is a bitio.Reader and bitio.Writer providing a bit buffer.
+// Similar to bytes.Buffer.
 type Buffer struct {
 	buf     []byte
 	bufBits int64

pkg/bitio/iobitreadseeker.go

@@ -5,13 +5,14 @@ import (
 	"io"
 )
 
-// IOBitReadSeeker is a bitio.ReadAtSeeker reading from a io.ReadSeeker
+// IOBitReadSeeker is a bitio.ReadAtSeeker reading from a io.ReadSeeker.
 type IOBitReadSeeker struct {
 	bitPos int64
 	rs     io.ReadSeeker
 	buf    []byte
 }
 
+// NewIOBitReadSeeker returns a new bitio.IOBitReadSeeker
 func NewIOBitReadSeeker(rs io.ReadSeeker) *IOBitReadSeeker {
 	return &IOBitReadSeeker{
 		bitPos: 0,

pkg/bitio/iobitwriter.go

@@ -4,14 +4,14 @@ import (
 	"io"
 )
 
-// IOBitWriter is a bitio.Writer that writes to a io.Writer
+// IOBitWriter is a bitio.Writer that writes to a io.Writer.
 // Use Flush to write possible unaligned byte zero bit padded.
 type IOBitWriter struct {
 	w io.Writer
 	b Buffer
 }
 
-// NewIOBitWriter returns a new bitio.IOBitWriter
+// NewIOBitWriter returns a new bitio.IOBitWriter.
 func NewIOBitWriter(w io.Writer) *IOBitWriter {
 	return &IOBitWriter{w: w}
 }

pkg/bitio/ioreader.go

@@ -5,15 +5,15 @@ import (
 	"io"
 )
 
-// IOReader is a io.Reader and io.ByteReader that reads from a bitio.Reader
-// Unaligned byte at EOF will be zero bit padded
+// IOReader is a io.Reader and io.ByteReader that reads from a bitio.Reader.
+// Unaligned byte at EOF will be zero bit padded.
 type IOReader struct {
 	r    Reader
 	rErr error
 	b    Buffer
 }
 
-// NewIOReader returns a new bitio.IOReader
+// NewIOReader returns a new bitio.IOReader.
 func NewIOReader(r Reader) *IOReader {
 	return &IOReader{r: r}
 }
@@ -22,8 +22,6 @@ func (r *IOReader) Read(p []byte) (n int, err error) {
 	var ns int64
 
 	for {
-		var err error
-
 		// uses p even if returning nothing, io.Reader docs says:
 		// "it may use all of p as scratch space during the call"
 		if r.rErr == nil {

pkg/bitio/ioreadseeker.go

@@ -1,14 +1,14 @@
 package bitio
 
-// IOReadSeeker is a io.ReadSeeker that reads from a bitio.ReadSeeker
-// Unaligned byte at EOF will be zero bit padded
+// IOReadSeeker is a io.ReadSeeker that reads from a bitio.ReadSeeker.
+// Unaligned byte at EOF will be zero bit padded.
 type IOReadSeeker struct {
 	IOReader
 	s    Seeker
 	sPos int64
 }
 
-// NewIOReadSeeker return a new bitio.IOReadSeeker
+// NewIOReadSeeker return a new bitio.IOReadSeeker.
 func NewIOReadSeeker(rs ReadSeeker) *IOReadSeeker {
 	return &IOReadSeeker{
 		IOReader: IOReader{r: rs},

pkg/bitio/limitreader.go

@@ -4,14 +4,14 @@ import (
 	"io"
 )
 
-// LimitReader is a bitio.Reader that reads a limited amount of bits from a bitio.Reader
-// Similar to bytes.LimitedReader
+// LimitReader is a bitio.Reader that reads a limited amount of bits from a bitio.Reader.
+// Similar to bytes.LimitedReader.
 type LimitReader struct {
 	r Reader
 	n int64
 }
 
-// NewLimitReader returns a new bitio.LimitReader
+// NewLimitReader returns a new bitio.LimitReader.
 func NewLimitReader(r Reader, n int64) *LimitReader { return &LimitReader{r, n} }
 
 func (l *LimitReader) ReadBits(p []byte, nBits int64) (n int64, err error) {

pkg/bitio/multireader.go

@@ -23,14 +23,15 @@ func endPos(rs Seeker) (int64, error) {
 	return e, nil
 }
 
-// MultiReader is a bitio.ReaderAtSeeker concatinating multiple bitio.ReadAtSeeker:s
-// Similar to io.MultiReader
+// MultiReader is a bitio.ReaderAtSeeker concatinating multiple bitio.ReadAtSeeker:s.
+// Similar to io.MultiReader.
 type MultiReader struct {
 	pos        int64
 	readers    []ReadAtSeeker
 	readerEnds []int64
 }
 
+// NewMultiReader returns a new bitio.MultiReader.
 func NewMultiReader(rs ...ReadAtSeeker) (*MultiReader, error) {
 	readerEnds := make([]int64, len(rs))
 	var esSum int64

pkg/bitio/reversebytes64.go

@@ -2,8 +2,8 @@ package bitio
 
 import "fmt"
 
-// ReverseBytes64 reverses the bytes part of the lowest nBits
-// Similar to bits.ReverseBytes64 but only rotates the lowest bytes and rest of bytes will be zero
+// ReverseBytes64 reverses the bytes part of the lowest nBits.
+// Similar to bits.ReverseBytes64 but only rotates the lowest bytes and rest of bytes will be zero.
 func ReverseBytes64(nBits int, n uint64) uint64 {
 	switch {
 	case nBits <= 8:

pkg/bitio/sectiontreader.go

@@ -4,8 +4,8 @@ import (
 	"io"
 )
 
-// SectionReader is a bitio.BitReaderAtSeeker reading a section of a bitio.ReaderAt
-// Similar to io.SectionReader
+// SectionReader is a bitio.BitReaderAtSeeker reading a section of a bitio.ReaderAt.
+// Similar to io.SectionReader.
 type SectionReader struct {
 	r        ReaderAt
 	bitBase  int64
@@ -13,7 +13,7 @@ type SectionReader struct {
 	bitLimit int64
 }
 
-// NewSectionReader returns a new bitio.SectionReader
+// NewSectionReader returns a new bitio.SectionReader.
 func NewSectionReader(r ReaderAt, bitOff int64, nBits int64) *SectionReader {
 	return &SectionReader{
 		r:        r,