Merge pull request moby#50503 from thaJeztah/pkg_stringid_docs

pkg/stringid: TruncateID: touch-up doc

Author: thaJeztah

pkg/stringid/stringid.go

@@ -12,10 +12,17 @@ const (
 	fullLen  = 64
 )
 
-// TruncateID returns a shorthand version of a string identifier for convenience.
-// A collision with other shorthands is very unlikely, but possible.
-// In case of a collision a lookup with TruncIndex.Get() will fail, and the caller
-// will need to use a longer prefix, or the full-length Id.
+// TruncateID returns a shorthand version of a string identifier for presentation.
+// For convenience, it accepts both digests ("sha256:xxxx") and IDs without an
+// algorithm prefix. It truncates the algorithm (if any) before truncating the
+// ID. The length of the truncated ID is currently fixed, but users should make
+// no assumptions of this to not change; it is merely a prefix of the ID that
+// provides enough uniqueness for common scenarios.
+//
+// Truncated IDs ("ID-prefixes") usually can be used to uniquely identify an
+// object (such as a container or network), but collisions may happen, in
+// which case an "ambiguous result" error is produced. In case of a collision,
+// the caller should try with a longer prefix or the full-length ID.
 func TruncateID(id string) string {
 	if i := strings.IndexRune(id, ':'); i >= 0 {
 		id = id[i+1:]