diff --git a/swarm/storage/types.go b/swarm/storage/types.go
index 8c70f45848..ada86831fc 100644
--- a/swarm/storage/types.go
+++ b/swarm/storage/types.go
@@ -80,6 +80,19 @@ func (a Address) bits(i, j uint) uint {
 	return res
 }
 
+// Proximity(x, y) returns the proximity order of the MSB distance between x and y
+//
+// The distance metric MSB(x, y) of two equal length byte sequences x an y is the
+// value of the binary integer cast of the x^y, ie., x and y bitwise xor-ed.
+// the binary cast is big endian: most significant bit first (=MSB).
+//
+// Proximity(x, y) is a discrete logarithmic scaling of the MSB distance.
+// It is defined as the reverse rank of the integer part of the base 2
+// logarithm of the distance.
+// It is calculated by counting the number of common leading zeros in the (MSB)
+// binary representation of the x^y.
+//
+// (0 farthest, 255 closest, 256 self)
 func Proximity(one, other []byte) (ret int) {
 	b := (MaxPO-1)/8 + 1
 	if b > len(one) {