Add documentation for token ring values (#1406)

https://docs.datastax.com/en/dse/6.7/dse-arch/datastax_enterprise/dbArch/archAboutDataDistribute.html

token.go

@@ -130,8 +130,15 @@ func (ht hostToken) String() string {
 // a data structure for organizing the relationship between tokens and hosts
 type tokenRing struct {
 	partitioner partitioner
-	tokens      []hostToken
-	hosts       []*HostInfo
+
+	// tokens map token range to primary replica.
+	// The elements in tokens are sorted by token ascending.
+	// The range for a given item in tokens starts after preceding range and ends with the token specified in
+	// token. The end token is part of the range.
+	// The lowest (i.e. index 0) range wraps around the ring (its preceding range is the one with largest index).
+	tokens []hostToken
+
+	hosts []*HostInfo
 }
 
 func newTokenRing(partitioner string, hosts []*HostInfo) (*tokenRing, error) {

topology.go

@@ -8,10 +8,16 @@ import (
 )
 
 type hostTokens struct {
+	// token is end (inclusive) of token range these hosts belong to
 	token token
 	hosts []*HostInfo
 }
 
+// tokenRingReplicas maps token ranges to list of replicas.
+// The elements in tokenRingReplicas are sorted by token ascending.
+// The range for a given item in tokenRingReplicas starts after preceding range and ends with the token specified in
+// token. The end token is part of the range.
+// The lowest (i.e. index 0) range wraps around the ring (its preceding range is the one with largest index).
 type tokenRingReplicas []hostTokens
 
 func (h tokenRingReplicas) Less(i, j int) bool { return h[i].token.Less(h[j].token) }