internal/store: improve doc comments

This improves readability on narrow 3:2 display.

Signed-off-by: Ophestra <cat@gensokyo.uk>

1 files changed, 56 insertions, 23 deletions

diff --git a/internal/store/store.go b/internal/store/store.go
index 3604521c..4383d55f 100644
--- a/internal/store/store.go
+++ b/internal/store/store.go
@@ -1,4 +1,5 @@
-// Package store implements cross-process state tracking for hakurei container instances.
+// Package store provides storage for hakurei instance states, safe for
+// concurrent and cross-process use.
 package store
 
 import (
@@ -15,11 +16,15 @@ import (
 	"hakurei.app/internal/lockedfile"
 )
 
-// MutexName is the pathname of the file backing [lockedfile.Mutex] of a [Store] and [Handle].
+// MutexName is the pathname of the file backing [lockedfile.Mutex] of a [Store]
+// and [Handle].
 const MutexName = "lock"
 
-// A Store keeps track of [hst.State] via a well-known filesystem accessible to all hakurei priv-side processes.
-// Access to store data and related resources are synchronised on a per-segment basis via [Handle].
+// A Store keeps track of [hst.State] via a well-known filesystem accessible to
+// all hakurei priv-side processes.
+//
+// Access to store data and related resources are synchronised on a per-segment
+// basis via [Handle].
 type Store struct {
 	// Pathname of directory that the store is rooted in.
 	base *check.Absolute
@@ -28,8 +33,10 @@ type Store struct {
 	handles sync.Map
 
 	// Inter-process mutex to synchronise operations against the entire store.
-	// Held during List and when initialising previously unknown identities during Do.
-	// Must not be accessed directly. Callers should use the bigLock method instead.
+	//
+	// Held during List and when initialising previously unknown identities
+	// during Do. Must not be accessed directly. Callers should use the bigLock
+	// method instead.
 	fileMu *lockedfile.Mutex
 
 	// For creating the base directory.
@@ -43,11 +50,17 @@ type Store struct {
 func (s *Store) bigLock() (unlock func(), err error) {
 	s.mkdirOnce.Do(func() { s.mkdirErr = os.MkdirAll(s.base.String(), 0700) })
 	if s.mkdirErr != nil {
-		return nil, &hst.AppError{Step: "create state store directory", Err: s.mkdirErr}
+		return nil, &hst.AppError{
+			Step: "create state store directory",
+			Err:  s.mkdirErr,
+		}
 	}
 
 	if unlock, err = s.fileMu.Lock(); err != nil {
-		return nil, &hst.AppError{Step: "acquire lock on the state store", Err: err}
+		return nil, &hst.AppError{
+			Step: "acquire lock on the state store",
+			Err:  err,
+		}
 	}
 	return
 }
@@ -73,7 +86,10 @@ func (s *Store) Handle(identity int) (*Handle, error) {
 		if err != nil && !errors.Is(err, fs.ErrExist) {
 			// handle methods will likely return ENOENT
 			s.handles.CompareAndDelete(identity, h)
-			return nil, &hst.AppError{Step: "create store segment directory", Err: err}
+			return nil, &hst.AppError{
+				Step: "create store segment directory",
+				Err:  err,
+			}
 		}
 	}
 	return h, nil
@@ -88,8 +104,9 @@ type SegmentIdentity struct {
 }
 
 // Segments returns an iterator over all [SegmentIdentity] known to the [Store].
-// To obtain a [Handle] on a segment, caller must then call [Store.Handle].
-// A non-nil error returned by segments is of type [hst.AppError].
+//
+// To obtain a [Handle] on a segment, caller must then call [Store.Handle]. A
+// non-nil error returned by segments is of type [hst.AppError].
 func (s *Store) Segments() (iter.Seq[SegmentIdentity], int, error) {
 	// read directory contents, should only contain storeMutexName and identity
 	var entries []os.DirEntry
@@ -102,7 +119,10 @@ func (s *Store) Segments() (iter.Seq[SegmentIdentity], int, error) {
 		unlock()
 
 		if err != nil && !errors.Is(err, os.ErrNotExist) {
-			return nil, -1, &hst.AppError{Step: "read store segments", Err: err}
+			return nil, -1, &hst.AppError{
+				Step: "read store segments",
+				Err:  err,
+			}
 		}
 	}
 
@@ -126,19 +146,25 @@ func (s *Store) Segments() (iter.Seq[SegmentIdentity], int, error) {
 				}
 
 				// this should never happen
-				si.Err = &hst.AppError{Step: step, Err: syscall.ENOTDIR,
-					Msg: "skipped non-directory entry " + strconv.Quote(ent.Name())}
+				si.Err = &hst.AppError{
+					Step: step, Err: syscall.ENOTDIR,
+					Msg: "skipped non-directory entry " + strconv.Quote(ent.Name()),
+				}
 				goto out
 			}
 
 			// failure paths either indicates a serious bug or external interference
 			if v, err := strconv.Atoi(ent.Name()); err != nil {
-				si.Err = &hst.AppError{Step: step, Err: err,
-					Msg: "skipped non-identity entry " + strconv.Quote(ent.Name())}
+				si.Err = &hst.AppError{
+					Step: step, Err: err,
+					Msg: "skipped non-identity entry " + strconv.Quote(ent.Name()),
+				}
 				goto out
 			} else if v < hst.IdentityStart || v > hst.IdentityEnd {
-				si.Err = &hst.AppError{Step: step, Err: syscall.ERANGE,
-					Msg: "skipped out of bounds entry " + strconv.Itoa(v)}
+				si.Err = &hst.AppError{
+					Step: step, Err: syscall.ERANGE,
+					Msg: "skipped out of bounds entry " + strconv.Itoa(v),
+				}
 				goto out
 			} else {
 				si.Identity = v
@@ -152,9 +178,11 @@ func (s *Store) Segments() (iter.Seq[SegmentIdentity], int, error) {
 	}, l, nil
 }
 
-// All returns a non-reusable iterator over all [EntryHandle] known to this [Store].
-// Callers must call copyError after completing iteration and handle the error accordingly.
-// A non-nil error returned by copyError is of type [hst.AppError].
+// All returns a non-reusable iterator over all [EntryHandle] known to this
+// [Store].
+//
+// Callers must call copyError after completing iteration and handle the error
+// accordingly. A non-nil error returned by copyError is of type [hst.AppError].
 func (s *Store) All() (entries iter.Seq[*EntryHandle], copyError func() error) {
 	var savedErr error
 	return func(yield func(*EntryHandle) bool) {
@@ -197,7 +225,12 @@ func (s *Store) All() (entries iter.Seq[*EntryHandle], copyError func() error) {
 }
 
 // New returns the address of a new instance of [Store].
-// Multiple instances of [Store] rooted in the same directory is possible, but unsupported.
+//
+// Multiple instances of [Store] rooted in the same directory is possible, but
+// unsupported.
 func New(base *check.Absolute) *Store {
-	return &Store{base: base, fileMu: lockedfile.MutexAt(base.Append(MutexName).String())}
+	return &Store{
+		base:   base,
+		fileMu: lockedfile.MutexAt(base.Append(MutexName).String()),
+	}
 }