doc: Update README and clean up godoc comments (#418)

Resolves: #417

Signed-off-by: Lixia (Sylvia) Lei <lixlei@microsoft.com>

README.md

@@ -3,35 +3,19 @@
 ![ORAS](https://github.com/oras-project/oras-www/raw/main/docs/assets/images/oras.png)
 
 ## Project status
+
 ### Versioning
 
 The ORAS Go library follows [Semantic Versioning](https://semver.org/), where breaking changes are reserved for MAJOR releases, and MINOR and PATCH releases must be 100% backwards compatible.
 
-### v1: stable
-
-[![Build Status](https://github.com/oras-project/oras-go/actions/workflows/build.yml/badge.svg?event=push&branch=v1)](https://github.com/oras-project/oras-go/actions/workflows/build.yml?query=workflow%3Abuild+event%3Apush+branch%3Av1)
-[![Go Report Card](https://goreportcard.com/badge/oras.land/oras-go)](https://goreportcard.com/report/oras.land/oras-go)
-[![Go Reference](https://pkg.go.dev/badge/oras.land/oras-go.svg)](https://pkg.go.dev/oras.land/oras-go)
-
-As there are various stable projects depending on the ORAS Go library, the
-[`v1`](https://github.com/oras-project/oras-go/tree/v1) branch
-is maintained for API stability, dependency updates, and security patches.
-All `v1.*` releases are based upon this branch.
-
-If you are seeking stability over new features, you are highly encouraged
-to use releases with major version `1`.
-
-### v2: experimental
+### v2: stable
 
 [![Build Status](https://github.com/oras-project/oras-go/actions/workflows/build.yml/badge.svg?event=push&branch=main)](https://github.com/oras-project/oras-go/actions/workflows/build.yml?query=workflow%3Abuild+event%3Apush+branch%3Amain)
 [![codecov](https://codecov.io/gh/oras-project/oras-go/branch/main/graph/badge.svg)](https://codecov.io/gh/oras-project/oras-go)
 [![Go Report Card](https://goreportcard.com/badge/oras.land/oras-go/v2)](https://goreportcard.com/report/oras.land/oras-go/v2)
 [![Go Reference](https://pkg.go.dev/badge/oras.land/oras-go/v2.svg)](https://pkg.go.dev/oras.land/oras-go/v2)
 
-In contrast to the `v1` branch, the
-[`main`](https://github.com/oras-project/oras-go/tree/main) branch
-is where all new feature development will occur.
-Any backward-incompatible changes will follow our [versioning policy](#versioning) and be reserved for the next major version of the library (`2`), which users may opt into.
+The version `2` is actively developed in the [`main`](https://github.com/oras-project/oras-go/tree/main) branch with all new features.
 
 Examples for common use cases can be found below:
 
@@ -40,13 +24,25 @@ Examples for common use cases can be found below:
 - [Repository interaction examples](https://pkg.go.dev/oras.land/oras-go/v2/registry/remote#pkg-examples)
 - [Authentication examples](https://pkg.go.dev/oras.land/oras-go/v2/registry/remote/auth#pkg-examples)
 
-If you are seeking new features over stability, you should use the
-`main` branch (or a specific commit hash) when including the ORAS
-Go library in your project's `go.mod`.
+If you are seeking latest changes, you should use the [`main`](https://github.com/oras-project/oras-go/tree/main) branch (or a specific commit hash) over a tagged version when including the ORAS Go library in your project's `go.mod`.
 The Go Reference for the `main` branch is available [here](https://pkg.go.dev/oras.land/oras-go/v2@main).
 
 To migrate from `v1` to `v2`, see [MIGRATION_GUIDE.md](./MIGRATION_GUIDE.md).
 
+### v1: stable
+
+[![Build Status](https://github.com/oras-project/oras-go/actions/workflows/build.yml/badge.svg?event=push&branch=v1)](https://github.com/oras-project/oras-go/actions/workflows/build.yml?query=workflow%3Abuild+event%3Apush+branch%3Av1)
+[![Go Report Card](https://goreportcard.com/badge/oras.land/oras-go)](https://goreportcard.com/report/oras.land/oras-go)
+[![Go Reference](https://pkg.go.dev/badge/oras.land/oras-go.svg)](https://pkg.go.dev/oras.land/oras-go)
+
+As there are various stable projects depending on the ORAS Go library `v1`, the
+[`v1`](https://github.com/oras-project/oras-go/tree/v1) branch
+is maintained for API stability, dependency updates, and security patches.
+All `v1.*` releases are based upon this branch.
+
+Since `v1` is in a maintenance state, you are highly encouraged
+to use releases with major version `2` for new features.
+
 ## Docs
 
 - [oras.land/client_libraries/go](https://oras.land/client_libraries/go/): Documentation for the ORAS Go library

content.go

@@ -54,7 +54,7 @@ const (
 // DefaultTagNOptions provides the default TagNOptions.
 var DefaultTagNOptions TagNOptions
 
-// TagNOptions contains parameters for oras.TagN.
+// TagNOptions contains parameters for [oras.TagN].
 type TagNOptions struct {
 	// Concurrency limits the maximum number of concurrent tag tasks.
 	// If less than or equal to 0, a default (currently 5) is used.
@@ -175,7 +175,7 @@ func Tag(ctx context.Context, target Target, src, dst string) (ocispec.Descripto
 // DefaultResolveOptions provides the default ResolveOptions.
 var DefaultResolveOptions ResolveOptions
 
-// ResolveOptions contains parameters for oras.Resolve.
+// ResolveOptions contains parameters for [oras.Resolve].
 type ResolveOptions struct {
 	// TargetPlatform ensures the resolved content matches the target platform
 	// if the node is a manifest, or selects the first resolved content that
@@ -246,7 +246,7 @@ func resolve(ctx context.Context, target ReadOnlyTarget, proxy *cas.Proxy, refer
 // DefaultFetchOptions provides the default FetchOptions.
 var DefaultFetchOptions FetchOptions
 
-// FetchOptions contains parameters for oras.Fetch.
+// FetchOptions contains parameters for [oras.Fetch].
 type FetchOptions struct {
 	// ResolveOptions contains parameters for resolving reference.
 	ResolveOptions
@@ -291,7 +291,7 @@ func Fetch(ctx context.Context, target ReadOnlyTarget, reference string, opts Fe
 // DefaultFetchBytesOptions provides the default FetchBytesOptions.
 var DefaultFetchBytesOptions FetchBytesOptions
 
-// FetchBytesOptions contains parameters for oras.FetchBytes.
+// FetchBytesOptions contains parameters for [oras.FetchBytes].
 type FetchBytesOptions struct {
 	// FetchOptions contains parameters for fetching content.
 	FetchOptions
@@ -342,7 +342,7 @@ func PushBytes(ctx context.Context, pusher content.Pusher, mediaType string, con
 // DefaultTagBytesNOptions provides the default TagBytesNOptions.
 var DefaultTagBytesNOptions TagBytesNOptions
 
-// TagBytesNOptions contains parameters for oras.TagBytesN.
+// TagBytesNOptions contains parameters for [oras.TagBytesN].
 type TagBytesNOptions struct {
 	// Concurrency limits the maximum number of concurrent tag tasks.
 	// If less than or equal to 0, a default (currently 5) is used.

content/file/file.go

@@ -62,14 +62,17 @@ const (
 )
 
 // Store represents a file system based store, which implements `oras.Target`.
+//
 // In the file store, the contents described by names are location-addressed
 // by file paths. Meanwhile, the file paths are mapped to a virtual CAS
 // where all metadata are stored in the memory.
+//
 // The contents that are not described by names are stored in a fallback storage,
 // which is a limited memory CAS by default.
 // As all the metadata are stored in the memory, the file store
 // cannot be restored from the file system.
-// After use, the file store needs to be closed by calling the `Close()` function.
+//
+// After use, the file store needs to be closed by calling the [Store.Close] function.
 // The file store cannot be used after being closed.
 type Store struct {
 	// TarReproducible controls if the tarballs generated

content/oci/oci.go

@@ -47,11 +47,11 @@ const ociImageIndexFile = "index.json"
 type Store struct {
 	// AutoSaveIndex controls if the OCI store will automatically save the index
 	// file on each Tag() call.
-	// If AutoSaveIndex is set to true, the OCI store will automatically call
-	// this method on each Tag() call.
-	// If AutoSaveIndex is set to false, it's the caller's responsibility
-	// to manually call SaveIndex() when needed.
-	// Default value: true.
+	//   - If AutoSaveIndex is set to true, the OCI store will automatically call
+	//     this method on each Tag() call.
+	//   - If AutoSaveIndex is set to false, it's the caller's responsibility
+	//     to manually call SaveIndex() when needed.
+	//   - Default value: true.
 	AutoSaveIndex bool
 	root          string
 	indexPath     string
@@ -257,10 +257,10 @@ func (s *Store) loadIndexFile(ctx context.Context) error {
 }
 
 // SaveIndex writes the `index.json` file to the file system.
-// If AutoSaveIndex is set to true (default value),
-// the OCI store will automatically call this method on each Tag() call.
-// If AutoSaveIndex is set to false, it's the caller's responsibility
-// to manually call this method when needed.
+//   - If AutoSaveIndex is set to true (default value),
+//     the OCI store will automatically call this method on each Tag() call.
+//   - If AutoSaveIndex is set to false, it's the caller's responsibility
+//     to manually call this method when needed.
 func (s *Store) SaveIndex() error {
 	s.indexLock.Lock()
 	defer s.indexLock.Unlock()

content/oci/readonlyoci.go

@@ -13,8 +13,6 @@ See the License for the specific language governing permissions and
 limitations under the License.
 */
 
-// Package oci provides access to an OCI content store.
-// Reference: https://github.com/opencontainers/image-spec/blob/v1.1.0-rc2/image-layout.md
 package oci
 
 import (

content/oci/storage.go

@@ -113,7 +113,7 @@ func (s *Storage) ingest(expected ocispec.Descriptor, content io.Reader) (path s
 	}
 
 	// create a temp file with the file name format "blobDigest_randomString"
-	// in the ingest direcotry.
+	// in the ingest directory.
 	// Go ensures that multiple programs or goroutines calling CreateTemp
 	// simultaneously will not choose the same file.
 	fp, err := os.CreateTemp(s.ingestRoot, expected.Digest.Encoded()+"_*")

copy.go

@@ -45,7 +45,7 @@ var DefaultCopyOptions CopyOptions = CopyOptions{
 	CopyGraphOptions: DefaultCopyGraphOptions,
 }
 
-// CopyOptions contains parameters for oras.Copy.
+// CopyOptions contains parameters for [oras.Copy].
 type CopyOptions struct {
 	CopyGraphOptions
 	// MapRoot maps the resolved root node to a desired root node for copy.
@@ -58,12 +58,12 @@ type CopyOptions struct {
 // WithTargetPlatform configures opts.MapRoot to select the manifest whose
 // platform matches the given platform. When MapRoot is provided, the platform
 // selection will be applied on the mapped root node.
-// - If the given platform is nil, no platform selection will be applied.
-// - If the root node is a manifest, it will remain the same if platform
-// matches, otherwise ErrNotFound will be returned.
-// - If the root node is a manifest list, it will be mapped to the first
-// matching manifest if exists, otherwise ErrNotFound will be returned.
-// - Otherwise ErrUnsupported will be returned.
+//   - If the given platform is nil, no platform selection will be applied.
+//   - If the root node is a manifest, it will remain the same if platform
+//     matches, otherwise ErrNotFound will be returned.
+//   - If the root node is a manifest list, it will be mapped to the first
+//     matching manifest if exists, otherwise ErrNotFound will be returned.
+//   - Otherwise ErrUnsupported will be returned.
 func (opts *CopyOptions) WithTargetPlatform(p *ocispec.Platform) {
 	if p == nil {
 		return
@@ -86,7 +86,7 @@ const defaultCopyMaxMetadataBytes int64 = 4 * 1024 * 1024 // 4 MiB
 // DefaultCopyGraphOptions provides the default CopyGraphOptions.
 var DefaultCopyGraphOptions CopyGraphOptions
 
-// CopyGraphOptions contains parameters for oras.CopyGraph.
+// CopyGraphOptions contains parameters for [oras.CopyGraph].
 type CopyGraphOptions struct {
 	// Concurrency limits the maximum number of concurrent copy tasks.
 	// If less than or equal to 0, a default (currently 3) is used.
@@ -115,6 +115,7 @@ type CopyGraphOptions struct {
 // in the source Target to the destination Target.
 // The destination reference will be the same as the source reference if the
 // destination reference is left blank.
+//
 // Returns the descriptor of the root node on successful copy.
 func Copy(ctx context.Context, src ReadOnlyTarget, srcRef string, dst Target, dstRef string, opts CopyOptions) (ocispec.Descriptor, error) {
 	if src == nil {

extendedcopy.go

@@ -38,7 +38,7 @@ var DefaultExtendedCopyOptions ExtendedCopyOptions = ExtendedCopyOptions{
 	ExtendedCopyGraphOptions: DefaultExtendedCopyGraphOptions,
 }
 
-// ExtendedCopyOptions contains parameters for oras.ExtendedCopy.
+// ExtendedCopyOptions contains parameters for [oras.ExtendedCopy].
 type ExtendedCopyOptions struct {
 	ExtendedCopyGraphOptions
 }
@@ -48,7 +48,7 @@ var DefaultExtendedCopyGraphOptions ExtendedCopyGraphOptions = ExtendedCopyGraph
 	CopyGraphOptions: DefaultCopyGraphOptions,
 }
 
-// ExtendedCopyGraphOptions contains parameters for oras.ExtendedCopyGraph.
+// ExtendedCopyGraphOptions contains parameters for [oras.ExtendedCopyGraph].
 type ExtendedCopyGraphOptions struct {
 	CopyGraphOptions
 	// Depth limits the maximum depth of the directed acyclic graph (DAG) that
@@ -65,6 +65,7 @@ type ExtendedCopyGraphOptions struct {
 // the given tagged node from the source GraphTarget to the destination Target.
 // The destination reference will be the same as the source reference if the
 // destination reference is left blank.
+//
 // Returns the descriptor of the tagged node on successful copy.
 func ExtendedCopy(ctx context.Context, src ReadOnlyGraphTarget, srcRef string, dst Target, dstRef string, opts ExtendedCopyOptions) (ocispec.Descriptor, error) {
 	if src == nil {
@@ -200,10 +201,13 @@ func findRoots(ctx context.Context, storage content.ReadOnlyGraphStorage, node o
 }
 
 // FilterAnnotation configures opts.FindPredecessors to filter the predecessors
-// whose annotation matches a given regex pattern. A predecessor is kept
-// if key is in its annotations and the annotation value matches regex.
+// whose annotation matches a given regex pattern.
+//
+// A predecessor is kept if key is in its annotations and the annotation value
+// matches regex.
 // If regex is nil, predecessors whose annotations contain key will be kept,
 // no matter of the annotation value.
+//
 // For performance consideration, when using both FilterArtifactType and
 // FilterAnnotation, it's recommended to call FilterArtifactType first.
 func (opts *ExtendedCopyGraphOptions) FilterAnnotation(key string, regex *regexp.Regexp) {
@@ -288,9 +292,11 @@ func fetchAnnotations(ctx context.Context, src content.ReadOnlyGraphStorage, des
 }
 
 // FilterArtifactType configures opts.FindPredecessors to filter the
-// predecessors whose artifact type matches a given regex pattern. A predecessor
-// is kept if its artifact type matches regex. If regex is nil, all
-// predecessors will be kept.
+// predecessors whose artifact type matches a given regex pattern.
+//
+// A predecessor is kept if its artifact type matches regex.
+// If regex is nil, all predecessors will be kept.
+//
 // For performance consideration, when using both FilterArtifactType and
 // FilterAnnotation, it's recommended to call FilterArtifactType first.
 func (opts *ExtendedCopyGraphOptions) FilterArtifactType(regex *regexp.Regexp) {

pack.go

@@ -44,7 +44,7 @@ const (
 // Reference: https://www.rfc-editor.org/rfc/rfc3339#section-5.6
 var ErrInvalidDateTimeFormat = errors.New("invalid date and time format")
 
-// PackOptions contains parameters for oras.Pack.
+// PackOptions contains parameters for [oras.Pack].
 type PackOptions struct {
 	// Subject is the subject of the manifest.
 	Subject *ocispec.Descriptor
@@ -70,6 +70,7 @@ type PackOptions struct {
 
 // Pack packs the given blobs, generates a manifest for the pack,
 // and pushes it to a content storage.
+//
 // When opts.PackImageManifest is true, artifactType will be used as the
 // the config descriptor mediaType of the image manifest.
 // If succeeded, returns a descriptor of the manifest.

registry/remote/auth/client.go

@@ -149,9 +149,10 @@ func (c *Client) SetUserAgent(userAgent string) {
 
 // Do sends the request to the remote server, attempting to resolve
 // authentication if 'Authorization' header is not set.
+//
 // On authentication failure due to bad credential,
-// - Do returns error if it fails to fetch token for bearer auth.
-// - Do returns the registry response without error for basic auth.
+//   - Do returns error if it fails to fetch token for bearer auth.
+//   - Do returns the registry response without error for basic auth.
 func (c *Client) Do(originalReq *http.Request) (*http.Response, error) {
 	if auth := originalReq.Header.Get("Authorization"); auth != "" {
 		return c.send(originalReq)

registry/remote/auth/scope.go

@@ -60,6 +60,7 @@ type scopesContextKey struct{}
 // WithScopes returns a context with scopes added. Scopes are de-duplicated.
 // Scopes are used as hints for the auth client to fetch bearer tokens with
 // larger scopes.
+//
 // For example, uploading blob to the repository "hello-world" does HEAD request
 // first then POST and PUT. The HEAD request will return a challenge for scope
 // `repository:hello-world:pull`, and the auth client will fetch a token for
@@ -69,8 +70,10 @@ type scopesContextKey struct{}
 // `repository:hello-world:pull,push`, the auth client with cache is hinted to
 // fetch a token via a single token fetch request for all the HEAD, POST, PUT
 // requests.
+//
 // Passing an empty list of scopes will virtually remove the scope hints in the
 // context.
+//
 // Reference: https://docs.docker.com/registry/spec/auth/scope/
 func WithScopes(ctx context.Context, scopes ...string) context.Context {
 	scopes = CleanScopes(scopes)
@@ -99,6 +102,7 @@ func GetScopes(ctx context.Context) []string {
 // the same resource type and name. The final scopes are sorted in ascending
 // order. In other words, the scopes passed in are de-duplicated and sorted.
 // Therefore, the output of this function is deterministic.
+//
 // If there is a wildcard `*` in the action, other actions in the same resource
 // type and name are ignored.
 func CleanScopes(scopes []string) []string {

registry/remote/registry.go

@@ -76,9 +76,10 @@ func (r *Registry) client() Client {
 // Ping checks whether or not the registry implement Docker Registry API V2 or
 // OCI Distribution Specification.
 // Ping can be used to check authentication when an auth client is configured.
+//
 // References:
-// - https://docs.docker.com/registry/spec/api/#base
-// - https://github.com/opencontainers/distribution-spec/blob/v1.1.0-rc1/spec.md#api
+//   - https://docs.docker.com/registry/spec/api/#base
+//   - https://github.com/opencontainers/distribution-spec/blob/v1.1.0-rc1/spec.md#api
 func (r *Registry) Ping(ctx context.Context) error {
 	url := buildRegistryBaseURL(r.PlainHTTP, r.Reference)
 	req, err := http.NewRequestWithContext(ctx, http.MethodGet, url, nil)
@@ -104,9 +105,11 @@ func (r *Registry) Ping(ctx context.Context) error {
 
 // Repositories lists the name of repositories available in the registry.
 // See also `RepositoryListPageSize`.
+//
 // If `last` is NOT empty, the entries in the response start after the
 // repo specified by `last`. Otherwise, the response starts from the top
 // of the Repositories list.
+//
 // Reference: https://docs.docker.com/registry/spec/api/#catalog
 func (r *Registry) Repositories(ctx context.Context, last string, fn func(repos []string) error) error {
 	ctx = auth.AppendScopes(ctx, auth.ScopeRegistryCatalog)