pkg/reference: SplitObject: add proper GoDoc

thaJeztah · thaJeztah · commit 57ce09b4284c · 2024-06-27T17:46:53.000+02:00
The behavior of this function is quite counter-intuitive, as it preserves the delimiter in the result. This function should probably have been an internal function, as its use for external consumers would be very limited, but let's at least document the (surprising) behavior for those that are considering to use it. It appears that BuildKit is currently the only (publicly visible) external consumer of this function; I am planning to inline its functionality in Spec.Digest() and to deprecate this function so that it can be removed. Signed-off-by: Sebastiaan van Stijn <github@gone.nl> (cherry picked from commit 4214595) Signed-off-by: Sebastiaan van Stijn <github@gone.nl>
diff --git a/reference/reference.go b/reference/reference.go
@@ -151,11 +151,19 @@ func (r Spec) String() string {
 	return r.Locator + ":" + r.Object
 }
 
-// SplitObject provides two parts of the object spec, delimited by an `@`
-// symbol.
+// SplitObject provides two parts of the object spec, delimited by an "@"
+// symbol. It does not perform any validation on correctness of the values
+// returned, and it's the callers' responsibility to validate the result.
 //
-// Either may be empty and it is the callers job to validate them
-// appropriately.
+// If an "@" delimiter is found, it returns the part *including* the "@"
+// delimiter as "tag", and the part after the "@" as digest.
+//
+// The example below produces "docker.io/library/ubuntu:latest@" and
+// "sha256:deadbeef";
+//
+//	t, d := SplitObject("docker.io/library/ubuntu:latest@sha256:deadbeef")
+//	fmt.Println(t) // docker.io/library/ubuntu:latest@
+//	fmt.Println(d) // sha256:deadbeef
 func SplitObject(obj string) (tag string, dgst digest.Digest) {
 	if i := strings.Index(obj, "@"); i >= 0 {
 		// Offset by one so preserve the "@" in the tag returned.
