chore: improves documentation

README.md

@@ -37,7 +37,7 @@ import (
 )
 
 func main() {
-    // the tree will use this namespace size
+    // the tree will use this namespace size (number of bytes)
     nidSize := 1
     // the leaves that will be pushed
     data := [][]byte{

hasher.go

@@ -165,19 +165,32 @@ func (n *Hasher) HashLeaf(leaf []byte) []byte {
 	return h.Sum(res)
 }
 
-// HashNode hashes inner nodes to:
-// minNID || maxNID || hash(NodePrefix || left || right), where left and right are the full
-// left and right child node bytes, including their respective min and max namespace IDs:
-// left = left.Min() || left.Max() || l.Hash().
-func (n *Hasher) HashNode(l, r []byte) []byte {
+// HashNode calculates a namespaced hash of a node using the
+// supplied left and right children. The input values, "left" and "right,"
+// are namespaced hash values with the format "minNID || maxNID || hash."
+// By default, the normal namespace hash calculation is followed,
+// which is "res = min(left.minNID, right.minNID) || max(left.maxNID,
+// right.maxNID) || H(NodePrefix, left,
+// right)". "res" refers to the return value of the HashNode.
+// However, if the "ignoreMaxNs" property of the Hasher is set to true,
+// the calculation of the namespace ID range of the node slightly changes.
+// In this case, when setting the upper range, the maximum possible namespace ID
+// (i.e., 2^NamespaceIDSize-1) should be ignored if possible.
+// This is achieved by taking the maximum value among the namespace IDs
+// available in the range of its left and right children (i.e.,
+// max(left.minNID, left.maxNID , right.minNID,
+// right.maxNID)), which is not equal to the maximum possible namespace ID value.
+// If such a namespace ID does not exist, the maximum NID is calculated
+// as normal, i.e., "res.maxNID = max(left.maxNID , right.maxNID).
+func (n *Hasher) HashNode(left, right []byte) []byte {
 	h := n.baseHasher
 	h.Reset()
 
 	// the actual hash result of the children got extended (or flagged) by their
 	// children's minNs || maxNs; hence the flagLen = 2 * NamespaceLen:
 	flagLen := 2 * n.NamespaceLen
-	leftMinNs, leftMaxNs := l[:n.NamespaceLen], l[n.NamespaceLen:flagLen]
-	rightMinNs, rightMaxNs := r[:n.NamespaceLen], r[n.NamespaceLen:flagLen]
+	leftMinNs, leftMaxNs := left[:n.NamespaceLen], left[n.NamespaceLen:flagLen]
+	rightMinNs, rightMaxNs := right[:n.NamespaceLen], right[n.NamespaceLen:flagLen]
 
 	minNs := min(leftMinNs, rightMinNs)
 	var maxNs []byte
@@ -193,11 +206,7 @@ func (n *Hasher) HashNode(l, r []byte) []byte {
 
 	// Note this seems a little faster than calling several Write()s on the
 	// underlying Hash function (see: https://github.com/google/trillian/pull/1503):
-	data := append(append(append(
-		make([]byte, 0, 1+len(l)+len(r)),
-		NodePrefix),
-		l...),
-		r...)
+	data := append(append(append(make([]byte, 0, 1+len(left)+len(right)), NodePrefix), left...), right...)
 	//nolint:errcheck
 	h.Write(data)
 	return h.Sum(res)

namespace/id.go

@@ -4,22 +4,27 @@ import "bytes"
 
 type ID []byte
 
+// Less returns true if nid < ID, otherwise, false.
 func (nid ID) Less(other ID) bool {
 	return bytes.Compare(nid, other) < 0
 }
 
+// Equal returns true if nid == ID, otherwise, false.
 func (nid ID) Equal(other ID) bool {
 	return bytes.Equal(nid, other)
 }
 
+// LessOrEqual returns true if nid <= ID, otherwise, false.
 func (nid ID) LessOrEqual(other ID) bool {
 	return bytes.Compare(nid, other) <= 0
 }
 
+// Size returns the byte size of the ID.
 func (nid ID) Size() IDSize {
 	return IDSize(len(nid))
 }
 
+// String stringifies the ID.
 func (nid ID) String() string {
 	return string(nid)
 }