docs: improve docs for OCI store (#941)

1. Add more detailed docs for `oci.Tag()` and `oci.Untag()`
2. Format existing docs

Resolves: #920

Signed-off-by: Lixia (Sylvia) Lei <[email protected]>

Author: Wwwsylvia

content/oci/oci.go

@@ -157,10 +157,11 @@ func (s *Store) Exists(ctx context.Context, target ocispec.Descriptor) (bool, er
 
 // Delete deletes the content matching the descriptor from the store. Delete may
 // fail on certain systems (i.e. NTFS), if there is a process (i.e. an unclosed
-// Reader) using target. If s.AutoGC is set to true, Delete will recursively
-// remove the dangling blobs caused by the current delete. If s.AutoDeleteReferrers
-// is set to true, Delete will recursively remove the referrers of the manifests
-// being deleted.
+// Reader) using target.
+//   - If s.AutoGC is set to true, Delete will recursively
+//     remove the dangling blobs caused by the current delete.
+//   - If s.AutoDeleteReferrers is set to true, Delete will recursively remove
+//     the referrers of the manifests being deleted.
 func (s *Store) Delete(ctx context.Context, target ocispec.Descriptor) error {
 	s.sync.Lock()
 	defer s.sync.Unlock()
@@ -220,8 +221,17 @@ func (s *Store) delete(ctx context.Context, target ocispec.Descriptor) ([]ocispe
 	return danglings, nil
 }
 
-// Tag tags a descriptor with a reference string.
-// reference should be a valid tag (e.g. "latest").
+// Tag associates a reference string (e.g. "latest") with the descriptor.
+// The reference string is recorded in the "org.opencontainers.image.ref.name"
+// annotation of the descriptor. When saved, the updated descriptor is persisted
+// in the `index.json` file.
+//
+//   - If the same reference string is tagged multiple times on different
+//     descriptors, the descriptor from the last call will be stored.
+//   - If the same descriptor is tagged multiple times with different reference
+//     strings, multiple copies of the descriptor with different reference tags
+//     will be stored in the `index.json` file.
+//
 // Reference: https://github.com/opencontainers/image-spec/blob/v1.1.1/image-layout.md#indexjson-file
 func (s *Store) Tag(ctx context.Context, desc ocispec.Descriptor, reference string) error {
 	s.sync.RLock()
@@ -260,11 +270,11 @@ func (s *Store) tag(ctx context.Context, desc ocispec.Descriptor, reference stri
 	return nil
 }
 
-// Resolve resolves a reference to a descriptor. If the reference to be resolved
-// is a tag, the returned descriptor will be a full descriptor declared by
-// github.com/opencontainers/image-spec/specs-go/v1. If the reference is a
-// digest the returned descriptor will be a plain descriptor (containing only
-// the digest, media type and size).
+// Resolve resolves a reference to a descriptor.
+//   - If the reference to be resolved is a tag, the returned descriptor will be
+//     a full descriptor declared by github.com/opencontainers/image-spec/specs-go/v1.
+//   - If the reference is a digest, the returned descriptor will be a
+//     plain descriptor (containing only the digest, media type and size).
 func (s *Store) Resolve(ctx context.Context, reference string) (ocispec.Descriptor, error) {
 	s.sync.RLock()
 	defer s.sync.RUnlock()
@@ -290,6 +300,13 @@ func (s *Store) Resolve(ctx context.Context, reference string) (ocispec.Descript
 	return desc, nil
 }
 
+// Untag disassociates a reference string from its descriptor.
+// When saved, the descriptor entry cotanining the reference in the
+// "org.opencontainers.image.ref.name" annotation is removed from the
+// `index.json` file.
+// The actual content identified by the descriptor is NOT deleted.
+//
+// Reference: https://github.com/opencontainers/image-spec/blob/v1.1.1/image-layout.md#indexjson-file
 func (s *Store) Untag(ctx context.Context, reference string) error {
 	if reference == "" {
 		return errdef.ErrMissingReference

content/oci/readonlyoci.go

@@ -83,11 +83,11 @@ func (s *ReadOnlyStore) Exists(ctx context.Context, target ocispec.Descriptor) (
 	return s.storage.Exists(ctx, target)
 }
 
-// Resolve resolves a reference to a descriptor. If the reference to be resolved
-// is a tag, the returned descriptor will be a full descriptor declared by
-// github.com/opencontainers/image-spec/specs-go/v1. If the reference is a
-// digest the returned descriptor will be a plain descriptor (containing only
-// the digest, media type and size).
+// Resolve resolves a reference to a descriptor.
+//   - If the reference to be resolved is a tag, the returned descriptor will be
+//     a full descriptor declared by github.com/opencontainers/image-spec/specs-go/v1.
+//   - If the reference is a digest, the returned descriptor will be a
+//     plain descriptor (containing only the digest, media type and size).
 func (s *ReadOnlyStore) Resolve(ctx context.Context, reference string) (ocispec.Descriptor, error) {
 	if reference == "" {
 		return ocispec.Descriptor{}, errdef.ErrMissingReference