feat: documentation

ring.go

@@ -12,16 +12,18 @@ type Ring[T any] struct {
 	offset       uint64 // Is not greater than 'size'.
 }
 
+// Cap returns the capacity of 'r'.
 func (r Ring[T]) Cap() int {
 	return len(r.data)
 }
 
+// Len returns the number of values in 'r'.
 func (r Ring[T]) Len() int {
 	return int(r.size)
 }
 
-// fetch returns the value of a certain index. The index MUST NOT be out of
-// range.
+// fetch returns the value of a certain index.
+// The index MUST NOT be out of range.
 func (r Ring[T]) fetch(index uint64) T {
 	if index >= r.size {
 		panic("Out of range!")
@@ -30,20 +32,26 @@ func (r Ring[T]) fetch(index uint64) T {
 	return r.data[(r.offset+index)%r.size]
 }
 
+// Get returns the value at a certain 'index' in 'r'.
+// The index must be within the range of the ring.
 func (r Ring[T]) Get(index int) T {
 	return r.fetch(uint64(index))
 }
 
+// Front returns the first value in 'r'.
+// The ring must not be empty.
 func (r Ring[T]) Front() T {
 	return r.fetch(0)
 }
 
+// Back returns the last value in 'r'.
+// The ring must not be empty.
 func (r Ring[T]) Back() T {
 	return r.fetch(r.size - 1)
 }
 
-// resize replaces the current data table with a new table a new 'capacity'. The
-// new capacity MUST NOT be less than [Ring.Len].
+// resize replaces the current data table with a new table a new 'capacity'.
+// The new capacity must not be less than [Ring.Len].
 func (r *Ring[T]) resize(capacity uint64) {
 	if capacity < r.size {
 		panic("Resize too small!")
@@ -58,8 +66,8 @@ func (r *Ring[T]) resize(capacity uint64) {
 	r.data = newData
 }
 
-// grow increases the size of the array by its growth factor. It is guaranteed
-// to not be [Ring.full].
+// grow increases the size of the array by its growth factor.
+// It is guaranteed to not be [Ring.full].
 func (r *Ring[T]) grow() {
 	if r.size == 0 {
 		r.resize(1)
@@ -73,8 +81,8 @@ func (r Ring[T]) full() bool {
 	return r.size == uint64(len(r.data))
 }
 
-// shrink decreases the size of the data table by its growth factor. Do not call
-// this when the data table is not [Ring.sparse].
+// shrink decreases the capacity of 'r' by its growth factor.
+// The ring must be [Ring.sparse].
 func (r *Ring[T]) shrink() {
 	r.resize(r.size / r.growthFactor)
 }
@@ -84,7 +92,8 @@ func (r *Ring[T]) sparse() bool {
 	return r.size*r.growthFactor < uint64(len(r.data))
 }
 
-// set updates the value of a certain index. The index MUST be in range.
+// set updates the value of a certain index.
+// The index must be in range.
 func (r Ring[T]) set(index uint64, value T) {
 	if index >= r.size {
 		panic("Out of range!")