swarm/pot: comments updated

swarm/pot/address.go

@@ -175,7 +175,7 @@ func DefaultPof(max int) func(one, other Val, pos int) (int, bool) {
 
 // proximityOrder returns two parameters:
 // 1. relative proximity order of the arguments one & other;
-// 2. boolean indicating is the full match occurred (one == other).
+// 2. boolean indicating whether the full match occurred (one == other).
 func proximityOrder(one, other []byte, pos int) (int, bool) {
 	for i := pos / 8; i < len(one); i++ {
 		if one[i] == other[i] {

swarm/pot/pot.go

@@ -147,7 +147,7 @@ func add(t *Pot, val Val, pof Pof) (*Pot, int, bool) {
 // Remove deletes element v from the Pot t and returns three parameters:
 // 1. new Pot that contains all the elements of t minus the element v;
 // 2. proximity order of the removed element v;
-// 3. boolean indicating if the item was found.
+// 3. boolean indicating whether the item was found.
 func Remove(t *Pot, v Val, pof Pof) (*Pot, int, bool) {
 	return remove(t, v, pof)
 }

swarm/pot/pot_test.go

@@ -82,6 +82,7 @@ func testAdd(t *Pot, pof Pof, j int, values ...string) (_ *Pot, n int, f bool) {
 	return t, n, f
 }
 
+// removing non-existing element from pot
 func TestPotRemoveNonExisting(t *testing.T) {
 	pof := DefaultPof(8)
 	n := NewPot(newTestAddr("00111100", 0), 0)
@@ -93,6 +94,9 @@ func TestPotRemoveNonExisting(t *testing.T) {
 	}
 }
 
+// this test creates hierarchical pot tree, and therefore any child node will have
+// child_po = parent_po + 1.
+// then removes a node from the middle of the tree.
 func TestPotRemoveSameBin(t *testing.T) {
 	pof := DefaultPof(8)
 	n := NewPot(newTestAddr("11111111", 0), 0)
@@ -117,6 +121,9 @@ func TestPotRemoveSameBin(t *testing.T) {
 	}
 }
 
+// this test creates a flat pot tree (all the elements are leafs of one root),
+// and therefore they all have the same po.
+// then removes an arbitrary element from the pot.
 func TestPotRemoveDifferentBins(t *testing.T) {
 	pof := DefaultPof(8)
 	n := NewPot(newTestAddr("11111111", 0), 0)