docs: improve README with package comments (#34)

Author: rootulp

README.md

@@ -1,6 +1,17 @@
 # go-square
 
-`go-square` is a Go library designed to provide utility functions for data square operations.
+[![Go Reference](https://pkg.go.dev/badge/github.com/celestiaorg/go-square.svg)](https://pkg.go.dev/github.com/celestiaorg/go-square)
+
+`go-square` is a Go module that provides data structures and utilities for interacting with data squares in the Celestia network. The data square is a special form of block serialization in the Celestia blockchain. This repo deals with the original data square which is distinct from the extended data square. Operations on the extended data square are handled by [rsmt2d](https://github.com/celestiaorg/rsmt2d).
+
+Package   | Description
+----------|---------------------------------------------------------------------------------------------------------------------
+blob      | Package blob provides types and functions for working with blobs, blob transactions, and index wrapper transactions.
+inclusion | Package inclusion contains functions to generate the blob share commitment from a given blob.
+merkle    | Package merkle computes a deterministic minimal height Merkle tree hash.
+namespace | Package namespace contains the Namespace data structure.
+shares    | Package shares contains the Share data structure.
+square    | Package square implements the logic to construct the original data square based on a list of transactions.
 
 ## Installation
 
@@ -38,4 +49,4 @@ make lint
 
 # Perform benchmarking
 make bench
-```
+```

blob/blob.go

@@ -1,3 +1,5 @@
+// Package blob provides types and functions for working with blobs, blob
+// transactions, and index wrapper transactions.
 package blob
 
 import (
@@ -98,6 +100,7 @@ func MarshalBlobTx(tx []byte, blobs ...*Blob) ([]byte, error) {
 	return proto.Marshal(bTx)
 }
 
+// Sort sorts the blobs by their namespace.
 func Sort(blobs []*Blob) {
 	sort.SliceStable(blobs, func(i, j int) bool {
 		return bytes.Compare(blobs[i].Namespace().Bytes(), blobs[j].Namespace().Bytes()) < 0

inclusion/blob_share_commitment_rules.go

@@ -7,9 +7,9 @@ import (
 	"golang.org/x/exp/constraints"
 )
 
-// BlobSharesUsedNonInteractiveDefaults returns the number of shares used by a given set
-// of blobs share lengths. It follows the blob share commitment rules and
-// returns the share indexes for each blob.
+// BlobSharesUsedNonInteractiveDefaults returns the number of shares used by a
+// given set of blobs share lengths. It follows the blob share commitment rules
+// and returns the total shares used and share indexes for each blob.
 func BlobSharesUsedNonInteractiveDefaults(cursor, subtreeRootThreshold int, blobShareLens ...int) (sharesUsed int, indexes []uint32) {
 	start := cursor
 	indexes = make([]uint32, len(blobShareLens))
@@ -34,13 +34,13 @@ func NextShareIndex(cursor, blobShareLen, subtreeRootThreshold int) int {
 	// merkle mountain range that makes up the blob share commitment (given the
 	// subtreeRootThreshold and the BlobMinSquareSize).
 	treeWidth := SubTreeWidth(blobShareLen, subtreeRootThreshold)
-	// We round up the cursor to the next multiple of this value i.e. if the cursor
-	// was at 13 and the tree width was 4, we return 16.
+	// Round up the cursor to the next multiple of treeWidth. For example, if
+	// the cursor was at 13 and the tree width is 4, return 16.
 	return RoundUpByMultipleOf(cursor, treeWidth)
 }
 
 // RoundUpByMultipleOf rounds cursor up to the next multiple of v. If cursor is divisible
-// by v, then it returns cursor
+// by v, then it returns cursor.
 func RoundUpByMultipleOf(cursor, v int) int {
 	if cursor%v == 0 {
 		return cursor
@@ -54,13 +54,11 @@ func BlobMinSquareSize(shareCount int) int {
 	return shares.RoundUpPowerOfTwo(int(math.Ceil(math.Sqrt(float64(shareCount)))))
 }
 
-// SubTreeWidth determines the maximum number of leaves per subtree in the share
+// SubTreeWidth returns the maximum number of leaves per subtree in the share
 // commitment over a given blob. The input should be the total number of shares
-// used by that blob. The reasoning behind this algorithm is discussed in depth
-// in ADR013
-// (celestia-app/docs/architecture/adr-013-non-interative-default-rules-for-zero-padding).
+// used by that blob. See ADR-013.
 func SubTreeWidth(shareCount, subtreeRootThreshold int) int {
-	// per ADR013, we use a predetermined threshold to determine width of sub
+	// Per ADR-013, we use a predetermined threshold to determine width of sub
 	// trees used to create share commitments
 	s := (shareCount / subtreeRootThreshold)
 

inclusion/commitment.go

@@ -43,15 +43,15 @@ func CreateCommitment(blob *blob.Blob, merkleRootFn MerkleRootFn, subtreeRootThr
 		cursor += treeSize
 	}
 
-	// create the commitments by pushing each leaf set onto an nmt
+	// create the commitments by pushing each leaf set onto an NMT
 	subTreeRoots := make([][]byte, len(leafSets))
 	for i, set := range leafSets {
-		// create the nmt todo(evan) use nmt wrapper
+		// Create the NMT. TODO: use NMT wrapper.
 		tree := nmt.New(sha256.New(), nmt.NamespaceIDSize(ns.NamespaceSize), nmt.IgnoreMaxNamespace(true))
 		for _, leaf := range set {
 			// the namespace must be added again here even though it is already
 			// included in the leaf to ensure that the hash will match that of
-			// the nmt wrapper (pkg/wrapper). Each namespace is added to keep
+			// the NMT wrapper (pkg/wrapper). Each namespace is added to keep
 			// the namespace in the share, and therefore the parity data, while
 			// also allowing for the manual addition of the parity namespace to
 			// the parity data.

inclusion/commitment_test.go

@@ -13,7 +13,7 @@ import (
 	"github.com/stretchr/testify/require"
 )
 
-func Test_MerkleMountainRangeHeights(t *testing.T) {
+func TestMerkleMountainRangeSizes(t *testing.T) {
 	type test struct {
 		totalSize  uint64
 		squareSize uint64

inclusion/doc.go

@@ -0,0 +1,3 @@
+// Package inclusion contains functions to generate the blob share commitment
+// from a given blob.
+package inclusion

namespace/namespace.go

@@ -1,3 +1,4 @@
+// Package namespace contains the Namespace data structure.
 package namespace
 
 import (

shares/shares.go

@@ -1,3 +1,4 @@
+// Package shares contains the Share data structure.
 package shares
 
 import (

square/square.go

@@ -1,3 +1,5 @@
+// Package square implements the logic to construct the original data square
+// based on a list of transactions.
 package square
 
 import (