Extra documentation for content interfaces.

Fixes: #7305

Signed-off-by: Nikita Rybak <nikita.rybak@gmail.com>

content/content.go

@@ -25,6 +25,26 @@ import (
 	ocispec "github.com/opencontainers/image-spec/specs-go/v1"
 )
 
+// Store combines the methods of content-oriented interfaces into a set that
+// are commonly provided by complete implementations.
+//
+// Overall content lifecycle:
+//   - Ingester is used to initiate a write operation (aka ingestion)
+//   - IngestManager is used to manage (e.g. list, abort) active ingestions
+//   - Once an ingestion is complete (see Writer.Commit), Provider is used to
+//     query a single piece of content by its digest
+//   - Manager is used to manage (e.g. list, delete) previously committed content
+//
+// Note that until ingestion is complete, its content is not visible through
+// Provider or Manager. Once ingestion is complete, it is no longer exposed
+// through IngestManager.
+type Store interface {
+	Manager
+	Provider
+	IngestManager
+	Ingester
+}
+
 // ReaderAt extends the standard io.ReaderAt interface with reporting of Size and io.Closer
 type ReaderAt interface {
 	io.ReaderAt
@@ -42,10 +62,30 @@ type Provider interface {
 
 // Ingester writes content
 type Ingester interface {
-	// Some implementations require WithRef to be included in opts.
+	// Writer initiates a writing operation (aka ingestion). A single ingestion
+	// is uniquely identified by its ref, provided using a WithRef option.
+	// Writer can be called multiple times with the same ref to access the same
+	// ingestion.
+	// Once all the data is written, use Writer.Commit to complete the ingestion.
 	Writer(ctx context.Context, opts ...WriterOpt) (Writer, error)
 }
 
+// IngestManager provides methods for managing ingestions. An ingestion is a
+// not-yet-complete writing operation initiated using Ingester and identified
+// by a ref string.
+type IngestManager interface {
+	// Status returns the status of the provided ref.
+	Status(ctx context.Context, ref string) (Status, error)
+
+	// ListStatuses returns the status of any active ingestions whose ref match
+	// the provided regular expression. If empty, all active ingestions will be
+	// returned.
+	ListStatuses(ctx context.Context, filters ...string) ([]Status, error)
+
+	// Abort completely cancels the ingest operation targeted by ref.
+	Abort(ctx context.Context, ref string) error
+}
+
 // Info holds content specific information
 //
 // TODO(stevvooe): Consider a very different name for this struct. Info is way
@@ -58,7 +98,7 @@ type Info struct {
 	Labels    map[string]string
 }
 
-// Status of a content operation
+// Status of a content operation (i.e. an ingestion)
 type Status struct {
 	Ref       string
 	Offset    int64
@@ -94,21 +134,7 @@ type Manager interface {
 	Delete(ctx context.Context, dgst digest.Digest) error
 }
 
-// IngestManager provides methods for managing ingests.
-type IngestManager interface {
-	// Status returns the status of the provided ref.
-	Status(ctx context.Context, ref string) (Status, error)
-
-	// ListStatuses returns the status of any active ingestions whose ref match the
-	// provided regular expression. If empty, all active ingestions will be
-	// returned.
-	ListStatuses(ctx context.Context, filters ...string) ([]Status, error)
-
-	// Abort completely cancels the ingest operation targeted by ref.
-	Abort(ctx context.Context, ref string) error
-}
-
-// Writer handles the write of content into a content store
+// Writer handles writing of content into a content store
 type Writer interface {
 	// Close closes the writer, if the writer has not been
 	// committed this allows resuming or aborting.
@@ -131,15 +157,6 @@ type Writer interface {
 	Truncate(size int64) error
 }
 
-// Store combines the methods of content-oriented interfaces into a set that
-// are commonly provided by complete implementations.
-type Store interface {
-	Manager
-	Provider
-	IngestManager
-	Ingester
-}
-
 // Opt is used to alter the mutable properties of content
 type Opt func(*Info) error