From fce75106f4be5e8ff08b7c567758645a7516eacc Mon Sep 17 00:00:00 2001
From: Runxi Yu
Date: Sun, 29 Mar 2026 09:37:52 +0000
Subject: object/store: Refine docs

---
 object/store/doc.go     | 10 ++++++++++
 object/store/errors.go  |  8 ++------
 object/store/writing.go |  9 ---------
 3 files changed, 12 insertions(+), 15 deletions(-)
 delete mode 100644 object/store/writing.go

diff --git a/object/store/doc.go b/object/store/doc.go
index 943dbea4..4e05f59c 100644
--- a/object/store/doc.go
+++ b/object/store/doc.go
@@ -1,5 +1,15 @@
 // Package objectstore provides interfaces for object storage backends.
 //
+// Object stores only respond to object-ID queries in terms of headers (type
+// and size), raw bytes, and streaming payloads, but they do not parse commits,
+// trees, blobs, or tags into typed values. Turning stored objects into typed
+// objects is the job of [codeberg.org/lindenii/furgit/object/fetch].
+//
+// This package also does not define a unified writing-store interface.
+// Backends have very different write models: writing one loose object is
+// natural, while writing one object into a packfile backend is wasteful.
+// A variety of writing interfaces may be added later.
+//
 // Concrete implementations generally inherit the contract documented by the
 // interfaces they satisfy. Implementation docs focus on additional guarantees
 // and implementation-specific behavior.
diff --git a/object/store/errors.go b/object/store/errors.go
index 3ee438f7..0e36b400 100644
--- a/object/store/errors.go
+++ b/object/store/errors.go
@@ -3,10 +3,6 @@ package objectstore
 import "errors"
 
 // ErrObjectNotFound indicates that an object does not exist in a backend.
-// 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).
+// This error must only be produced by object stores, when it has no
+// specified object ID, but no other unexpected conditions were encountered.
 var ErrObjectNotFound = errors.New("objectstore: object not found")
diff --git a/object/store/writing.go b/object/store/writing.go
deleted file mode 100644
index e673f6eb..00000000
--- a/object/store/writing.go
+++ /dev/null
@@ -1,9 +0,0 @@
-package objectstore
-
-// There is currently no writing-store interface because different
-// object store backends have very different models for writing.
-// For example, a loose object store can trivially write single loose
-// objects, but writing individual objects to a packfile store would
-// be extremely wasteful.
-//
-// At some time, we will have writing-store interfaces.
-- 
cgit v1.3.1-10-gc9f91