commitgraph: Tighten docs and use a value-ish Filter return

6 files changed, 16 insertions, 9 deletions

diff --git a/commitgraph/bloom/filter.go b/commitgraph/bloom/filter.go
index 7c4aa1b8..395dd5ce 100644
--- a/commitgraph/bloom/filter.go
+++ b/commitgraph/bloom/filter.go
@@ -15,14 +15,12 @@ type Filter struct {
 }
 
 // NewFilter constructs one query-ready bloom filter from raw data/settings.
-func NewFilter(data []byte, settings Settings) *Filter {
-	out := &Filter{
+func NewFilter(data []byte, settings Settings) Filter {
+	return Filter{
 		Data:           data,
 		HashVersion:    settings.HashVersion,
 		NumHashes:      settings.NumHashes,
 		BitsPerEntry:   settings.BitsPerEntry,
 		MaxChangePaths: settings.MaxChangePaths,
 	}
-
-	return out
 }
diff --git a/commitgraph/read/bloom.go b/commitgraph/read/bloom.go
index c7e3e426..eca88c36 100644
--- a/commitgraph/read/bloom.go
+++ b/commitgraph/read/bloom.go
@@ -38,20 +38,23 @@ func (reader *Reader) BloomVersion() uint8 {
 
 // BloomFilterAt returns one commit's changed-path Bloom filter.
 //
+// The returned filter borrows reader-owned mapped commit-graph data and is
+// only valid until the reader is closed.
+//
 // Returns BloomUnavailableError when this commit graph has no Bloom data.
-func (reader *Reader) BloomFilterAt(pos Position) (*bloom.Filter, error) {
+func (reader *Reader) BloomFilterAt(pos Position) (bloom.Filter, error) {
 	layer, err := reader.layerByPosition(pos)
 	if err != nil {
-		return nil, err
+		return bloom.Filter{}, err
 	}
 
 	if layer.chunkBloomIndex == nil || layer.chunkBloomData == nil || layer.bloomSettings == nil {
-		return nil, &BloomUnavailableError{Pos: pos}
+		return bloom.Filter{}, &BloomUnavailableError{Pos: pos}
 	}
 
 	start, end, err := bloomRange(layer, pos.Index)
 	if err != nil {
-		return nil, err
+		return bloom.Filter{}, err
 	}
 
 	filter := bloom.NewFilter(
diff --git a/commitgraph/read/close.go b/commitgraph/read/close.go
index d91c7762..f8b6141a 100644
--- a/commitgraph/read/close.go
+++ b/commitgraph/read/close.go
@@ -1,6 +1,8 @@
 package read
 
 // Close releases all mapped commit-graph files.
+//
+// Repeated calls to Close are undefined behavior.
 func (reader *Reader) Close() error {
 	var closeErr error
 
diff --git a/commitgraph/read/open.go b/commitgraph/read/open.go
index 9ae9ca94..cfcb4ff8 100644
--- a/commitgraph/read/open.go
+++ b/commitgraph/read/open.go
@@ -8,6 +8,8 @@ import (
 )
 
 // Open opens commit-graph data from one objects root.
+//
+// Open borrows root during construction and does not close it.
 func Open(root *os.Root, algo objectid.Algorithm, mode OpenMode) (*Reader, error) {
 	if algo.Size() == 0 {
 		return nil, objectid.ErrInvalidAlgorithm
diff --git a/commitgraph/read/read_test.go b/commitgraph/read/read_test.go
index bebf76dc..dc14377d 100644
--- a/commitgraph/read/read_test.go
+++ b/commitgraph/read/read_test.go
@@ -282,7 +282,7 @@ func commitParents(tb testing.TB, reader *read.Reader, commit read.Commit) []obj
 	return out
 }
 
-func assertChangedPathsBloomPositive(tb testing.TB, testRepo *testgit.TestRepo, filter *bloom.Filter, commitID objectid.ObjectID) {
+func assertChangedPathsBloomPositive(tb testing.TB, testRepo *testgit.TestRepo, filter bloom.Filter, commitID objectid.ObjectID) {
 	tb.Helper()
 
 	changedPaths := testRepo.Run(tb, "diff-tree", "--no-commit-id", "--name-only", "-r", "--root", commitID.String())
diff --git a/commitgraph/read/reader.go b/commitgraph/read/reader.go
index 922d459b..ab68f31c 100644
--- a/commitgraph/read/reader.go
+++ b/commitgraph/read/reader.go
@@ -5,6 +5,8 @@ import "codeberg.org/lindenii/furgit/objectid"
 // Reader provides read-only access to one mmap-backed commit-graph snapshot.
 //
 // It is safe for concurrent read-only queries.
+// Values returned by Reader methods are only valid until the reader is closed
+// when explicitly documented on that method.
 type Reader struct {
 	algo        objectid.Algorithm
 	hashVersion uint8