internal/outcome: improve doc comments

This improves readability on smaller displays.

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

1 files changed, 60 insertions, 24 deletions

diff --git a/internal/outcome/outcome.go b/internal/outcome/outcome.go
index 3516eaef..42b50389 100644
--- a/internal/outcome/outcome.go
+++ b/internal/outcome/outcome.go
@@ -1,4 +1,5 @@
-// Package outcome implements the outcome of the privileged and container sides of a hakurei container.
+// Package outcome implements the outcome of the privileged and container sides
+// of a hakurei container.
 package outcome
 
 import (
@@ -27,8 +28,9 @@ func Info() *hst.Info {
 	return &hi
 }
 
-// envAllocSize is the initial size of the env map pre-allocated when the configured env map is nil.
-// It should be large enough to fit all insertions by outcomeOp.toContainer.
+// envAllocSize is the initial size of the env map pre-allocated when the
+// configured env map is nil. It should be large enough to fit all insertions by
+// outcomeOp.toContainer.
 const envAllocSize = 1 << 6
 
 func newInt(v int) *stringPair[int] { return &stringPair[int]{v, strconv.Itoa(v)} }
@@ -43,7 +45,8 @@ func (s *stringPair[T]) unwrap() T      { return s.v }
 func (s *stringPair[T]) String() string { return s.s }
 
 // outcomeState is copied to the shim process and available while applying outcomeOp.
-// This is transmitted from the priv side to the shim, so exported fields should be kept to a minimum.
+// This is transmitted from the priv side to the shim, so exported fields should
+// be kept to a minimum.
 type outcomeState struct {
 	// Params only used by the shim process. Populated by populateEarly.
 	Shim *shimParams
@@ -89,10 +92,15 @@ func (s *outcomeState) valid() bool {
 		s.Paths != nil
 }
 
-// newOutcomeState returns the address of a new outcomeState with its exported fields populated via syscallDispatcher.
+// newOutcomeState returns the address of a new outcomeState with its exported
+// fields populated via syscallDispatcher.
 func newOutcomeState(k syscallDispatcher, msg message.Msg, id *hst.ID, config *hst.Config, hsu *Hsu) *outcomeState {
 	s := outcomeState{
-		Shim:      &shimParams{PrivPID: k.getpid(), Verbose: msg.IsVerbose()},
+		Shim: &shimParams{
+			PrivPID: k.getpid(),
+			Verbose: msg.IsVerbose(),
+		},
+
 		ID:        id,
 		Identity:  config.Identity,
 		UserID:    hsu.MustID(msg),
@@ -121,6 +129,7 @@ func newOutcomeState(k syscallDispatcher, msg message.Msg, id *hst.ID, config *h
 }
 
 // populateLocal populates unexported fields from transmitted exported fields.
+//
 // These fields are cheaper to recompute per-process.
 func (s *outcomeState) populateLocal(k syscallDispatcher, msg message.Msg) error {
 	if !s.valid() || k == nil || msg == nil {
@@ -136,7 +145,10 @@ func (s *outcomeState) populateLocal(k syscallDispatcher, msg message.Msg) error
 	s.id = &stringPair[hst.ID]{*s.ID, s.ID.String()}
 
 	s.Copy(&s.sc, s.UserID)
-	msg.Verbosef("process share directory at %q, runtime directory at %q", s.sc.SharePath, s.sc.RunDirPath)
+	msg.Verbosef(
+		"process share directory at %q, runtime directory at %q",
+		s.sc.SharePath, s.sc.RunDirPath,
+	)
 
 	s.identity = newInt(s.Identity)
 	s.mapuid, s.mapgid = newInt(s.Mapuid), newInt(s.Mapgid)
@@ -146,17 +158,25 @@ func (s *outcomeState) populateLocal(k syscallDispatcher, msg message.Msg) error
 }
 
 // instancePath returns a path formatted for outcomeStateSys.instance.
+//
 // This method must only be called from outcomeOp.toContainer if
 // outcomeOp.toSystem has already called outcomeStateSys.instance.
-func (s *outcomeState) instancePath() *check.Absolute { return s.sc.SharePath.Append(s.id.String()) }
+func (s *outcomeState) instancePath() *check.Absolute {
+	return s.sc.SharePath.Append(s.id.String())
+}
 
 // runtimePath returns a path formatted for outcomeStateSys.runtime.
+//
 // This method must only be called from outcomeOp.toContainer if
 // outcomeOp.toSystem has already called outcomeStateSys.runtime.
-func (s *outcomeState) runtimePath() *check.Absolute { return s.sc.RunDirPath.Append(s.id.String()) }
+func (s *outcomeState) runtimePath() *check.Absolute {
+	return s.sc.RunDirPath.Append(s.id.String())
+}
 
 // outcomeStateSys wraps outcomeState and [system.I]. Used on the priv side only.
-// Implementations of outcomeOp must not access fields other than sys unless explicitly stated.
+//
+// Implementations of outcomeOp must not access fields other than sys unless
+// explicitly stated.
 type outcomeStateSys struct {
 	// Whether XDG_RUNTIME_DIR is used post hsu.
 	useRuntimeDir bool
@@ -219,6 +239,7 @@ func (state *outcomeStateSys) ensureRuntimeDir() {
 }
 
 // instance returns the pathname to a process-specific directory within TMPDIR.
+//
 // This directory must only hold entries bound to [system.Process].
 func (state *outcomeStateSys) instance() *check.Absolute {
 	if state.sharePath != nil {
@@ -230,6 +251,7 @@ func (state *outcomeStateSys) instance() *check.Absolute {
 }
 
 // runtime returns the pathname to a process-specific directory within XDG_RUNTIME_DIR.
+//
 // This directory must only hold entries bound to [system.Process].
 func (state *outcomeStateSys) runtime() *check.Absolute {
 	if state.runtimeSharePath != nil {
@@ -242,22 +264,29 @@ func (state *outcomeStateSys) runtime() *check.Absolute {
 	return state.runtimeSharePath
 }
 
-// outcomeStateParams wraps outcomeState and [container.Params]. Used on the shim side only.
+// outcomeStateParams wraps outcomeState and [container.Params].
+//
+// Used on the shim side only.
 type outcomeStateParams struct {
-	// Overrides the embedded [container.Params] in [container.Container]. The Env field must not be used.
+	// Overrides the embedded [container.Params] in [container.Container].
+	//
+	// The Env field must not be used.
 	params *container.Params
 	// Collapsed into the Env slice in [container.Params] by the final outcomeOp.
 	env map[string]string
 
-	// Filesystems with the optional root sliced off if present. Populated by spParamsOp.
-	// Safe for use by spFilesystemOp.
+	// Filesystems with the optional root sliced off if present.
+	//
+	// Populated by spParamsOp. Safe for use by spFilesystemOp.
 	filesystem []hst.FilesystemConfigJSON
 
 	// Inner XDG_RUNTIME_DIR default formatting of `/run/user/%d` via mapped uid.
+	//
 	// Populated by spRuntimeOp.
 	runtimeDir *check.Absolute
 
 	// Path to pipewire-pulse server.
+	//
 	// Populated by spPipeWireOp if DirectPipeWire is false.
 	pipewirePulsePath *check.Absolute
 
@@ -265,25 +294,32 @@ type outcomeStateParams struct {
 	*outcomeState
 }
 
-// errNotEnabled is returned by outcomeOp.toSystem and used internally to exclude an outcomeOp from transmission.
+// errNotEnabled is returned by outcomeOp.toSystem and used internally to
+// exclude an outcomeOp from transmission.
 var errNotEnabled = errors.New("op not enabled in the configuration")
 
-// An outcomeOp inflicts an outcome on [system.I] and contains enough information to
-// inflict it on [container.Params] in a separate process.
-// An implementation of outcomeOp must store cross-process states in exported fields only.
+// An outcomeOp inflicts an outcome on [system.I] and contains enough
+// information to inflict it on [container.Params] in a separate process.
+//
+// An implementation of outcomeOp must store cross-process states in exported
+// fields only.
 type outcomeOp interface {
 	// toSystem inflicts the current outcome on [system.I] in the priv side process.
 	toSystem(state *outcomeStateSys) error
 
-	// toContainer inflicts the current outcome on [container.Params] in the shim process.
-	// The implementation must not write to the Env field of [container.Params] as it will be overwritten
-	// by flattened env map.
+	// toContainer inflicts the current outcome on [container.Params] in the
+	// shim process.
+	//
+	// Implementations must not write to the Env field of [container.Params]
+	// as it will be overwritten by flattened env map.
 	toContainer(state *outcomeStateParams) error
 }
 
-// toSystem calls the outcomeOp.toSystem method on all outcomeOp implementations and populates shimParams.Ops.
-// This function assumes the caller has already called the Validate method on [hst.Config]
-// and checked that it returns nil.
+// toSystem calls the outcomeOp.toSystem method on all outcomeOp implementations
+// and populates shimParams.Ops.
+//
+// This function assumes the caller has already called the Validate method on
+// [hst.Config] and checked that it returns nil.
 func (state *outcomeStateSys) toSystem() error {
 	if state.Shim == nil || state.Shim.Ops != nil {
 		return newWithMessage("invalid ops state reached")