objectstore: Clarify docs

1 files changed, 13 insertions, 2 deletions

diff --git a/objectstore/objectstore.go b/objectstore/objectstore.go
index 58967147..2592c1b1 100644
--- a/objectstore/objectstore.go
+++ b/objectstore/objectstore.go
@@ -10,8 +10,12 @@ import (
 )
 
 // ErrObjectNotFound indicates that an object does not exist in a backend.
-// TODO: This might need to be an interface or otherwise be able to encapsulate multiple concrete backends'.
-// XXX: Don't remove this in favor of errors.ObjectMissingError yet due to pressure of allocation large error structs.
+// This error MUST only be used in situations where the object store has
+// no specified object ID, but no other unexpected conditions were
+// encountered. In particular, it is not suitable for situations where one
+// object references another (such as a tree referencing a blob) but
+// the latter does not exist; these situations should use a separate
+// error (TODO).
 var ErrObjectNotFound = errors.New("objectstore: object not found")
 
 // Store reads Git objects by object ID.
@@ -22,26 +26,33 @@ type Store interface {
 	// the requested object ID. Readers should treat this as a repository
 	// invariant and should not re-verify it on every read.
 	ReadBytesFull(id objectid.ObjectID) ([]byte, error)
+
 	// ReadBytesContent reads an object's type and content bytes.
 	ReadBytesContent(id objectid.ObjectID) (objecttype.Type, []byte, error)
+
 	// ReadReaderFull reads a full serialized object stream as "type size\0content".
 	// Caller must close the returned reader.
 	ReadReaderFull(id objectid.ObjectID) (io.ReadCloser, error)
+
 	// ReadReaderContent reads an object's type, declared content length,
 	// and content stream.
 	// Caller must close the returned reader.
 	ReadReaderContent(id objectid.ObjectID) (objecttype.Type, int64, io.ReadCloser, error)
+
 	// ReadSize reads an object's declared content length.
 	//
 	// This is equivalent to ReadHeader(...).size and may be cheaper than
 	// ReadHeader when callers do not need object type.
 	ReadSize(id objectid.ObjectID) (int64, error)
+
 	// ReadHeader reads an object's type and declared content length.
 	ReadHeader(id objectid.ObjectID) (objecttype.Type, int64, error)
+
 	// Refresh updates any backend-local discovery/cache view of on-disk objects.
 	//
 	// Backends without dynamic discovery should return nil.
 	Refresh() error
+
 	// Close releases resources associated with the backend.
 	Close() error
 }