chore: adding comments for LinkedMap functions

txpool/pool.go

@@ -54,7 +54,7 @@ func (p *txPool) SetNewSandboxAndRecheck(sb sandbox.Sandbox) {
 
 	var next *linkedmap.LinkNode[linkedmap.Pair[tx.ID, *tx.Tx]]
 	for _, pool := range p.pools {
-		for e := pool.FirstNode(); e != nil; e = next {
+		for e := pool.HeadNode(); e != nil; e = next {
 			next = e.Next
 			trx := e.Data.Value
 
@@ -152,31 +152,31 @@ func (p *txPool) PrepareBlockTransactions() block.Txs {
 
 	// Appending one sortition transaction
 	poolSortition := p.pools[payload.PayloadTypeSortition]
-	for n := poolSortition.FirstNode(); n != nil; n = n.Next {
+	for n := poolSortition.HeadNode(); n != nil; n = n.Next {
 		trxs = append(trxs, n.Data.Value)
 	}
 
 	// Appending bond transactions
 	poolBond := p.pools[payload.PayloadTypeBond]
-	for n := poolBond.FirstNode(); n != nil; n = n.Next {
+	for n := poolBond.HeadNode(); n != nil; n = n.Next {
 		trxs = append(trxs, n.Data.Value)
 	}
 
 	// Appending unbond transactions
 	poolUnbond := p.pools[payload.PayloadTypeUnbond]
-	for n := poolUnbond.FirstNode(); n != nil; n = n.Next {
+	for n := poolUnbond.HeadNode(); n != nil; n = n.Next {
 		trxs = append(trxs, n.Data.Value)
 	}
 
 	// Appending withdraw transactions
 	poolWithdraw := p.pools[payload.PayloadTypeWithdraw]
-	for n := poolWithdraw.FirstNode(); n != nil; n = n.Next {
+	for n := poolWithdraw.HeadNode(); n != nil; n = n.Next {
 		trxs = append(trxs, n.Data.Value)
 	}
 
 	// Appending send transactions
 	poolSend := p.pools[payload.PayloadTypeTransfer]
-	for n := poolSend.FirstNode(); n != nil; n = n.Next {
+	for n := poolSend.HeadNode(); n != nil; n = n.Next {
 		trxs = append(trxs, n.Data.Value)
 	}
 

util/linkedmap/linkedmap.go

@@ -1,7 +1,5 @@
 package linkedmap
 
-// TODO: should be thread safe or not?
-
 type Pair[K comparable, V any] struct {
 	Key   K
 	Value V
@@ -13,6 +11,7 @@ type LinkedMap[K comparable, V any] struct {
 	capacity int
 }
 
+// NewLinkedMap creates a new LinkedMap with the specified capacity.
 func NewLinkedMap[K comparable, V any](capacity int) *LinkedMap[K, V] {
 	return &LinkedMap[K, V]{
 		list:     NewDoublyLinkedList[Pair[K, V]](),
@@ -21,21 +20,24 @@ func NewLinkedMap[K comparable, V any](capacity int) *LinkedMap[K, V] {
 	}
 }
 
+// SetCapacity sets the capacity of the LinkedMap and prunes the excess elements if needed.
 func (lm *LinkedMap[K, V]) SetCapacity(capacity int) {
 	lm.capacity = capacity
 
 	lm.prune()
 }
 
+// Has checks if the specified key exists in the LinkedMap.
 func (lm *LinkedMap[K, V]) Has(key K) bool {
 	_, found := lm.hashmap[key]
 	return found
 }
 
+// PushBack adds a new key-value pair to the end of the LinkedMap.
 func (lm *LinkedMap[K, V]) PushBack(key K, value V) {
 	ln, found := lm.hashmap[key]
 	if found {
-		// update the second
+		// Update the value if the key already exists
 		ln.Data.Value = value
 		return
 	}
@@ -47,10 +49,11 @@ func (lm *LinkedMap[K, V]) PushBack(key K, value V) {
 	lm.prune()
 }
 
+// PushFront adds a new key-value pair to the beginning of the LinkedMap.
 func (lm *LinkedMap[K, V]) PushFront(key K, value V) {
 	ln, found := lm.hashmap[key]
 	if found {
-		// update the second
+		// Update the value if the key already exists
 		ln.Data.Value = value
 		return
 	}
@@ -62,6 +65,7 @@ func (lm *LinkedMap[K, V]) PushFront(key K, value V) {
 	lm.prune()
 }
 
+// GetNode returns the LinkNode corresponding to the specified key.
 func (lm *LinkedMap[K, V]) GetNode(key K) *LinkNode[Pair[K, V]] {
 	ln, found := lm.hashmap[key]
 	if found {
@@ -70,52 +74,62 @@ func (lm *LinkedMap[K, V]) GetNode(key K) *LinkNode[Pair[K, V]] {
 	return nil
 }
 
-func (lm *LinkedMap[K, V]) LastNode() *LinkNode[Pair[K, V]] {
+// TailNode returns the LinkNode at the end (tail) of the LinkedMap.
+func (lm *LinkedMap[K, V]) TailNode() *LinkNode[Pair[K, V]] {
 	ln := lm.list.Tail
 	if ln == nil {
 		return nil
 	}
 	return ln
 }
 
-func (lm *LinkedMap[K, V]) FirstNode() *LinkNode[Pair[K, V]] {
+// HeadNode returns the LinkNode at the beginning (head) of the LinkedMap.
+func (lm *LinkedMap[K, V]) HeadNode() *LinkNode[Pair[K, V]] {
 	ln := lm.list.Head
 	if ln == nil {
 		return nil
 	}
 	return ln
 }
 
+// Remove removes the key-value pair with the specified key from the LinkedMap.
+// It returns true if the key was found and removed, otherwise false.
 func (lm *LinkedMap[K, V]) Remove(key K) bool {
-	nl, found := lm.hashmap[key]
+	ln, found := lm.hashmap[key]
 	if found {
-		lm.list.Delete(nl)
-		delete(lm.hashmap, nl.Data.Key)
+		lm.list.Delete(ln)
+		delete(lm.hashmap, ln.Data.Key)
 	}
 	return found
 }
 
+// Empty checks if the LinkedMap is empty (contains no key-value pairs).
 func (lm *LinkedMap[K, V]) Empty() bool {
 	return lm.Size() == 0
 }
 
+// Capacity returns the capacity of the LinkedMap.
 func (lm *LinkedMap[K, V]) Capacity() int {
 	return lm.capacity
 }
 
+// Size returns the number of key-value pairs in the LinkedMap.
 func (lm *LinkedMap[K, V]) Size() int {
 	return lm.list.Length()
 }
 
+// Full checks if the LinkedMap is full (reached its capacity).
 func (lm *LinkedMap[K, V]) Full() bool {
 	return lm.list.Length() == lm.capacity
 }
 
+// Clear removes all key-value pairs from the LinkedMap, making it empty.
 func (lm *LinkedMap[K, V]) Clear() {
 	lm.list.Clear()
 	lm.hashmap = make(map[K]*LinkNode[Pair[K, V]])
 }
 
+// prune removes excess elements from the LinkedMap if its size exceeds the capacity.
 func (lm *LinkedMap[K, V]) prune() {
 	for lm.list.Length() > lm.capacity {
 		front := lm.list.Head

util/linkedmap/linkedmap_test.go

@@ -10,26 +10,26 @@ import (
 func TestLinkedMap(t *testing.T) {
 	t.Run("Test FirstNode", func(t *testing.T) {
 		lm := NewLinkedMap[int, string](4)
-		assert.Nil(t, lm.FirstNode())
+		assert.Nil(t, lm.HeadNode())
 
 		lm.PushFront(3, "c")
 		lm.PushFront(2, "b")
 		lm.PushFront(1, "a")
 
-		assert.Equal(t, lm.FirstNode().Data.Key, 1)
-		assert.Equal(t, lm.FirstNode().Data.Value, "a")
+		assert.Equal(t, lm.HeadNode().Data.Key, 1)
+		assert.Equal(t, lm.HeadNode().Data.Value, "a")
 	})
 
 	t.Run("Test LastNode", func(t *testing.T) {
 		lm := NewLinkedMap[int, string](4)
-		assert.Nil(t, lm.LastNode())
+		assert.Nil(t, lm.TailNode())
 
 		lm.PushBack(1, "a")
 		lm.PushBack(2, "b")
 		lm.PushBack(3, "c")
 
-		assert.Equal(t, lm.LastNode().Data.Key, 3)
-		assert.Equal(t, lm.LastNode().Data.Value, "c")
+		assert.Equal(t, lm.TailNode().Data.Key, 3)
+		assert.Equal(t, lm.TailNode().Data.Value, "c")
 	})
 
 	t.Run("Test Get", func(t *testing.T) {
@@ -118,7 +118,7 @@ func TestLinkedMap(t *testing.T) {
 		lm.PushBack(3, "c")
 		lm.PushBack(4, "d")
 
-		n := lm.FirstNode()
+		n := lm.HeadNode()
 		assert.Equal(t, n.Data.Key, 2)
 		assert.Equal(t, n.Data.Value, "b")
 	})
@@ -131,7 +131,7 @@ func TestLinkedMap(t *testing.T) {
 		lm.PushFront(3, "c")
 		lm.PushFront(4, "d") // This item should be pruned
 
-		n := lm.LastNode()
+		n := lm.TailNode()
 		assert.Equal(t, n.Data.Key, 1)
 		assert.Equal(t, n.Data.Value, "a")
 	})
@@ -145,8 +145,8 @@ func TestLinkedMap(t *testing.T) {
 
 		lm.Remove(1)
 
-		assert.Equal(t, lm.FirstNode().Data.Key, 2)
-		assert.Equal(t, lm.FirstNode().Data.Value, "b")
+		assert.Equal(t, lm.HeadNode().Data.Key, 2)
+		assert.Equal(t, lm.HeadNode().Data.Value, "b")
 	})
 
 	t.Run("Delete last", func(t *testing.T) {
@@ -158,8 +158,8 @@ func TestLinkedMap(t *testing.T) {
 
 		lm.Remove(3)
 
-		assert.Equal(t, lm.LastNode().Data.Key, 2)
-		assert.Equal(t, lm.LastNode().Data.Value, "b")
+		assert.Equal(t, lm.TailNode().Data.Key, 2)
+		assert.Equal(t, lm.TailNode().Data.Value, "b")
 	})
 
 	t.Run("Test Has function", func(t *testing.T) {