docs: update example tests (#932)

This PR:
1. Update the outdated examples involving `Pack` and `ArtifactManifest`.
2. Add numbered step documentation to the two package level examples of
copy, so that there is a consistency with the other four package level
examples.
3. Minor fixes such as renaming examples.

Fixes #818 
Signed-off-by: Xiaoxuan Wang <[email protected]>

Author: wangxiaoxuan273

content/example_test.go

@@ -20,6 +20,8 @@ import (
 	"fmt"
 	"io"
 
+	_ "crypto/sha256"
+
 	ocispec "github.com/opencontainers/image-spec/specs-go/v1"
 	"oras.land/oras-go/v2/content"
 )

content/file/example_test.go

@@ -67,7 +67,7 @@ func TestMain(m *testing.M) {
 }
 
 // Example_packFiles gives an example of adding files and generating a manifest
-// referencing the files.
+// referencing the files as defined in image-spec v1.1.1.
 func Example_packFiles() {
 	store, err := file.New(workingDir)
 	if err != nil {
@@ -92,7 +92,10 @@ func Example_packFiles() {
 
 	// 2. Generate a manifest referencing the files
 	artifactType := "example/test"
-	manifestDescriptor, err := oras.Pack(ctx, store, artifactType, fileDescriptors, oras.PackOptions{})
+	opts := oras.PackManifestOptions{
+		Layers: fileDescriptors,
+	}
+	manifestDescriptor, err := oras.PackManifest(ctx, store, oras.PackManifestVersion1_1, artifactType, opts)
 	if err != nil {
 		panic(err)
 	}
@@ -101,5 +104,5 @@ func Example_packFiles() {
 	// Output:
 	// file descriptor for foo.txt: {example/file sha256:2c26b46b68ffc68ff99b453c1d30413413422d706483bfa0f98a5e886266e7ae 3 [] map[org.opencontainers.image.title:foo.txt] [] <nil> }
 	// file descriptor for bar.txt: {example/file sha256:fcde2b2edba56bf408601fb721fe9b5c338d10ee429ea04fae5511b68fbf8fb9 3 [] map[org.opencontainers.image.title:bar.txt] [] <nil> }
-	// manifest media type: application/vnd.oci.artifact.manifest.v1+json
+	// manifest media type: application/vnd.oci.image.manifest.v1+json
 }

example_copy_test.go

@@ -189,7 +189,7 @@ func TestMain(m *testing.M) {
 	os.Exit(m.Run())
 }
 
-func ExampleCopy_remoteToRemote() {
+func ExampleCopy_repositoryToRepository() {
 	reg, err := remote.NewRegistry(remoteHost)
 	if err != nil {
 		panic(err) // Handle error
@@ -199,7 +199,7 @@ func ExampleCopy_remoteToRemote() {
 	if err != nil {
 		panic(err) // Handle error
 	}
-	dst, err := reg.Repository(ctx, "target")
+	dst, err := reg.Repository(ctx, "destination")
 	if err != nil {
 		panic(err) // Handle error
 	}
@@ -215,7 +215,7 @@ func ExampleCopy_remoteToRemote() {
 	// sha256:7cbb44b44e8ede5a89cf193db3f5f2fd019d89697e6b87e8ed2589e60649b0d1
 }
 
-func ExampleCopy_remoteToRemoteWithMount() {
+func ExampleCopy_repositoryToRepositoryWithMount() {
 	reg, err := remote.NewRegistry(remoteHost)
 	if err != nil {
 		panic(err) // Handle error
@@ -225,7 +225,7 @@ func ExampleCopy_remoteToRemoteWithMount() {
 	if err != nil {
 		panic(err) // Handle error
 	}
-	dst, err := reg.Repository(ctx, "target")
+	dst, err := reg.Repository(ctx, "destination")
 	if err != nil {
 		panic(err) // Handle error
 	}
@@ -241,7 +241,7 @@ func ExampleCopy_remoteToRemoteWithMount() {
 
 	// Enable cross-repository blob mounting
 	opts.MountFrom = func(ctx context.Context, desc ocispec.Descriptor) ([]string, error) {
-		// the slice of source repositores may also come from a database of known locations of blobs
+		// the slice of source repositories may also come from a database of known locations of blobs
 		return []string{"source/repository/name"}, nil
 	}
 
@@ -255,7 +255,7 @@ func ExampleCopy_remoteToRemoteWithMount() {
 	// Final sha256:7cbb44b44e8ede5a89cf193db3f5f2fd019d89697e6b87e8ed2589e60649b0d1
 }
 
-func ExampleCopy_remoteToLocal() {
+func ExampleCopy_repositoryToMemory() {
 	reg, err := remote.NewRegistry(remoteHost)
 	if err != nil {
 		panic(err) // Handle error
@@ -279,7 +279,7 @@ func ExampleCopy_remoteToLocal() {
 	// sha256:7cbb44b44e8ede5a89cf193db3f5f2fd019d89697e6b87e8ed2589e60649b0d1
 }
 
-func ExampleCopy_localToLocal() {
+func ExampleCopy_memoryToMemory() {
 	src := exampleMemoryStore
 	dst := memory.New()
 
@@ -295,7 +295,7 @@ func ExampleCopy_localToLocal() {
 	// sha256:7cbb44b44e8ede5a89cf193db3f5f2fd019d89697e6b87e8ed2589e60649b0d1
 }
 
-func ExampleCopy_localToOciFile() {
+func ExampleCopy_memoryToOCIStore() {
 	src := exampleMemoryStore
 	tempDir, err := os.MkdirTemp("", "oras_oci_example_*")
 	if err != nil {
@@ -319,14 +319,14 @@ func ExampleCopy_localToOciFile() {
 	// sha256:7cbb44b44e8ede5a89cf193db3f5f2fd019d89697e6b87e8ed2589e60649b0d1
 }
 
-func ExampleCopy_localToRemote() {
+func ExampleCopy_memoryToRepository() {
 	src := exampleMemoryStore
 	reg, err := remote.NewRegistry(remoteHost)
 	if err != nil {
 		panic(err) // Handle error
 	}
 	ctx := context.Background()
-	dst, err := reg.Repository(ctx, "target")
+	dst, err := reg.Repository(ctx, "destination")
 	if err != nil {
 		panic(err) // Handle error
 	}
@@ -342,27 +342,34 @@ func ExampleCopy_localToRemote() {
 	// sha256:7cbb44b44e8ede5a89cf193db3f5f2fd019d89697e6b87e8ed2589e60649b0d1
 }
 
-// ExampleCopyArtifactManifestRemoteToLocal gives an example of copying
-// an artifact manifest from a remote repository into memory.
-func Example_copyArtifactManifestRemoteToLocal() {
-	src, err := remote.NewRepository(fmt.Sprintf("%s/source", remoteHost))
+// ExampleCopyArtifactFromRepository gives an example of copying
+// an artifact from a remote repository into memory.
+func Example_copyArtifactFromRepository() {
+	// 0. Connect to a remote repository
+	repositoryName := "source"
+	src, err := remote.NewRepository(fmt.Sprintf("%s/%s", remoteHost, repositoryName))
 	if err != nil {
 		panic(err)
 	}
+
+	// 1. Create a memory store
 	dst := memory.New()
 	ctx := context.Background()
 
+	// 2. Resolve the descriptor of the artifact from the digest
 	exampleDigest := "sha256:70c29a81e235dda5c2cebb8ec06eafd3cca346cbd91f15ac74cefd98681c5b3d"
 	descriptor, err := src.Resolve(ctx, exampleDigest)
 	if err != nil {
 		panic(err)
 	}
+
+	// 3. Copy the artifact from the remote repository
 	err = oras.CopyGraph(ctx, src, dst, descriptor, oras.DefaultCopyGraphOptions)
 	if err != nil {
 		panic(err)
 	}
 
-	// verify that the artifact manifest described by the descriptor exists in dst
+	// 4. Verify that the artifact manifest described by the descriptor exists in dst
 	contentExists, err := dst.Exists(ctx, descriptor)
 	if err != nil {
 		panic(err)
@@ -373,17 +380,22 @@ func Example_copyArtifactManifestRemoteToLocal() {
 	// true
 }
 
-// ExampleExtendedCopyArtifactAndReferrersRemoteToLocal gives an example of
+// ExampleExtendedCopyArtifactAndReferrersFromRepository gives an example of
 // copying an artifact along with its referrers from a remote repository into
 // memory.
-func Example_extendedCopyArtifactAndReferrersRemoteToLocal() {
-	src, err := remote.NewRepository(fmt.Sprintf("%s/source", remoteHost))
+func Example_extendedCopyArtifactAndReferrersFromRepository() {
+	// 0. Connect to a remote repository
+	repositoryName := "source"
+	src, err := remote.NewRepository(fmt.Sprintf("%s/%s", remoteHost, repositoryName))
 	if err != nil {
 		panic(err)
 	}
+
+	// 1. Create a memory store
 	dst := memory.New()
 	ctx := context.Background()
 
+	// 2. Copy the artifact and its referrers from the remote repository
 	tagName := "latest"
 	// ExtendedCopy will copy the artifact tagged by "latest" along with all of its
 	// referrers from src to dst.