Index: common/cmpbin/doc.go |
diff --git a/common/cmpbin/doc.go b/common/cmpbin/doc.go |
index 2974be238017f3d753ca93bb459c7a58c48e30a3..70741e49b948b93389579f7e11de18c7b2d62e29 100644 |
--- a/common/cmpbin/doc.go |
+++ b/common/cmpbin/doc.go |
@@ -5,7 +5,13 @@ |
// Package cmpbin provides binary serialization routines which ensure that the |
// serialized objects maintain the same sort order of the original inputs when |
// sorted bytewise (i.e. with memcmp). Additionally, serialized objects are |
-// concatenatable. |
+// concatenatable, and the concatenated items will behave as if they're compared |
+// field-to-field. So, for example, comparing each string in a []string would |
+// compare the same way as comparing the concatenation of those strings encoded |
+// with cmpbin. Simply concatenating the strings without encoding them will |
+// NOT retain this property, as you could not distinguish []string{"a", "aa"} |
+// from []string{"aa", "a"}. With cmpbin, these two would unambiguously sort as |
+// ("a", "aa") < ("aa", "a"). |
// |
// Notes on particular serialization schemes: |
// |