From 3587a3145067f4806ca821ee6801ccf989d53a92 Mon Sep 17 00:00:00 2001
From: Shiwei Zhang <shizh@microsoft.com>
Date: Tue, 9 Jan 2024 18:40:45 +0800
Subject: [PATCH] docs: add example to parse ref with digest

Signed-off-by: Shiwei Zhang <shizh@microsoft.com>
---
 registry/example_reference_test.go | 47 ++++++++++++++++++++++++++++++
 registry/reference.go              |  2 ++
 2 files changed, 49 insertions(+)
 create mode 100644 registry/example_reference_test.go

diff --git a/registry/example_reference_test.go b/registry/example_reference_test.go
new file mode 100644
index 00000000..45cb3b7a
--- /dev/null
+++ b/registry/example_reference_test.go
@@ -0,0 +1,47 @@
+/*
+Copyright The ORAS Authors.
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+*/
+
+package registry_test
+
+import (
+	_ "crypto/sha256" // required to parse sha256 digest. See [Reference.Digest]
+	"fmt"
+
+	"oras.land/oras-go/v2/registry"
+)
+
+// ExampleParseReference_digest demonstrates parsing a reference string with
+// digest and print its components.
+func ExampleParseReference_digest() {
+	rawRef := "ghcr.io/oras-project/oras-go@sha256:601d05a48832e7946dab8f49b14953549bebf42e42f4d7973b1a5a287d77ab76"
+	ref, err := registry.ParseReference(rawRef)
+	if err != nil {
+		panic(err)
+	}
+
+	fmt.Println("Registry:", ref.Registry)
+	fmt.Println("Repository:", ref.Repository)
+
+	digest, err := ref.Digest()
+	if err != nil {
+		panic(err)
+	}
+	fmt.Println("Digest:", digest)
+
+	// Output:
+	// Registry: ghcr.io
+	// Repository: oras-project/oras-go
+	// Digest: sha256:601d05a48832e7946dab8f49b14953549bebf42e42f4d7973b1a5a287d77ab76
+}
diff --git a/registry/reference.go b/registry/reference.go
index a4d2003d..18f36bfd 100644
--- a/registry/reference.go
+++ b/registry/reference.go
@@ -250,6 +250,8 @@ func (r Reference) ReferenceOrDefault() string {
 }
 
 // Digest returns the reference as a digest.
+// Corresponding cryptographic hash implementations are required to be imported
+// as specified by https://pkg.go.dev/github.com/opencontainers/go-digest#readme-usage
 func (r Reference) Digest() (digest.Digest, error) {
 	return digest.Parse(r.Reference)
 }