Add a bit more documentation flavor to cmpbin.

common/cmpbin/doc.go

 // Copyright 2015 The Chromium Authors. All rights reserved.
 // Use of this source code is governed by a BSD-style license that can be
 // found in the LICENSE file.
 
 // 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:
 //
 // - Numbers:
 // The number encoding is less efficient on average than Varint
 // ("encoding/binary") for small numbers (it has a minimum encoded size of
 // 2 bytes), but is more efficient for large numbers (it has a maximum encoded
 // size of 9 bytes for a 64 bit int, unlike the largest Varint which has a 10b
 // representation).
 //
@@ skipping 63 matching lines @@
 //   - SNaN                    - 0xFFF0000000000001
 //   - +inf                    - 0xFFF0000000000000
 //   - MaxFloat64              - 0xFFEFFFFFFFFFFFFF
 //   - SmallestNonzeroFloat64  - 0x8000000000000001
 //   - 0                       - 0x8000000000000000
 //   - -0                      - 0x7FFFFFFFFFFFFFFF
 //   - -SmallestNonzeroFloat64 - 0x7FFFFFFFFFFFFFFE
 //   - -MaxFloat64             - 0x0010000000000000
 //   - -inf                    - 0x000FFFFFFFFFFFFF
 package cmpbin