reference: ParseDockerRef: slight refactor, and update docs

- improve documentation
- remove redundant error-check
- simplify interface matching, which slightly improves readability
- touch-up some docs

Signed-off-by: Sebastiaan van Stijn <github@gone.nl>

reference/sort.go

@@ -20,14 +20,16 @@ import (
 	"sort"
 )
 
-// Sort sorts string references preferring higher information references
+// Sort sorts string references preferring higher information references.
+//
 // The precedence is as follows:
-// 1. Name + Tag + Digest
-// 2. Name + Tag
-// 3. Name + Digest
-// 4. Name
-// 5. Digest
-// 6. Parse error
+//
+//  1. [Named] + [Tagged] + [Digested] (e.g., "docker.io/library/busybox:latest@sha256:<digest>")
+//  2. [Named] + [Tagged]              (e.g., "docker.io/library/busybox:latest")
+//  3. [Named] + [Digested]            (e.g., "docker.io/library/busybo@sha256:<digest>")
+//  4. [Named]                         (e.g., "docker.io/library/busybox")
+//  5. [Digested]                      (e.g., "docker.io@sha256:<digest>")
+//  6. Parse error
 func Sort(references []string) []string {
 	var prefs []Reference
 	var bad []string