diff --git a/roaring/roaring.go b/roaring/roaring.go
index 577c7c4c5..16e6159d7 100644
--- a/roaring/roaring.go
+++ b/roaring/roaring.go
@@ -2865,7 +2865,8 @@ func (*op) size() int { return 1 + 8 + 4 }
 func highbits(v uint64) uint64 { return uint64(v >> 16) }
 func lowbits(v uint64) uint16  { return uint16(v & 0xFFFF) }
 
-// search32 returns the index of v in a.
+// search32 returns the index of value in a. If value is not found, it works the
+// same way as search64.
 func search32(a []uint16, value uint16) int {
 	// Optimize for elements and the last element.
 	n := len(a)
@@ -2902,7 +2903,13 @@ func search32(a []uint16, value uint16) int {
 	return -(lo + 1)
 }
 
-// search64 returns the index of v in a.
+// search64 returns the index of value in a. If value is not found, -1 * (1 +
+// the index where v would be if it were inserted) is returned. This is done in
+// order to both signal that value was not found (negative number), and also
+// return information about where v would go if it were inserted. The +1 offset
+// is necessary due to the case where v is not found, but would go at index 0.
+// since negative 0 is no different from positive 0, we offset the returned
+// negative indices by 1. See the test for this function for examples.
 func search64(a []uint64, value uint64) int {
 	// Optimize for elements and the last element.
 	n := len(a)