internal/app: update doc comments

A lot of these comments are quite old and have not been updated to reflect changes.

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

4 files changed, 16 insertions, 18 deletions

diff --git a/hst/config.go b/hst/config.go
index ee216faa..bd8f637b 100644
--- a/hst/config.go
+++ b/hst/config.go
@@ -87,7 +87,9 @@ type (
 
 		// initial process environment variables
 		Env map[string]string `json:"env"`
-		// map target user uid to privileged user uid in the user namespace
+		// map target user uid to privileged user uid in the user namespace;
+		// some programs fail to connect to dbus session running as a different uid,
+		// this option works around it by mapping priv-side caller uid in container
 		MapRealUID bool `json:"map_real_uid"`
 
 		// pass through all devices
diff --git a/internal/app/app.go b/internal/app/app.go
index 359a0ce8..506703c2 100644
--- a/internal/app/app.go
+++ b/internal/app/app.go
@@ -1,19 +1,16 @@
-// Package app defines the generic [App] interface.
+// Package app implements high-level hakurei container behaviour.
 package app
 
 import (
-	"context"
-	"log"
 	"syscall"
 	"time"
 
 	"hakurei.app/hst"
 	"hakurei.app/internal/app/state"
-	"hakurei.app/internal/sys"
 )
 
 type App interface {
-	// ID returns a copy of [ID] held by App.
+	// ID returns a copy of [state.ID] held by App.
 	ID() state.ID
 
 	// Seal determines the outcome of config as a [SealedApp].
@@ -51,11 +48,3 @@ func (rs *RunState) SetStart() {
 	now := time.Now().UTC()
 	rs.Time = &now
 }
-
-func MustNew(ctx context.Context, os sys.State) App {
-	a, err := New(ctx, os)
-	if err != nil {
-		log.Fatalf("cannot create app: %v", err)
-	}
-	return a
-}
diff --git a/internal/app/app_linux.go b/internal/app/app_linux.go
index 1563f99d..bdfc9eaf 100644
--- a/internal/app/app_linux.go
+++ b/internal/app/app_linux.go
@@ -3,6 +3,7 @@ package app
 import (
 	"context"
 	"fmt"
+	"log"
 	"sync"
 
 	"hakurei.app/hst"
@@ -22,6 +23,14 @@ func New(ctx context.Context, os sys.State) (App, error) {
 	return a, err
 }
 
+func MustNew(ctx context.Context, os sys.State) App {
+	a, err := New(ctx, os)
+	if err != nil {
+		log.Fatalf("cannot create app: %v", err)
+	}
+	return a
+}
+
 type app struct {
 	id  *stringPair[state.ID]
 	sys sys.State
diff --git a/internal/app/container_linux.go b/internal/app/container_linux.go
index cd423ad6..cdefe170 100644
--- a/internal/app/container_linux.go
+++ b/internal/app/container_linux.go
@@ -16,8 +16,7 @@ import (
 	"hakurei.app/system/dbus"
 )
 
-// in practice there should be less than 30 entries added by the runtime;
-// allocating slightly more as a margin for future expansion
+// in practice there should be less than 30 system mount points
 const preallocateOpsCount = 1 << 5
 
 // newContainer initialises [container.Params] via [hst.ContainerConfig].
@@ -67,8 +66,6 @@ func newContainer(s *hst.ContainerConfig, os sys.State, prefix string, uid, gid
 	}
 
 	if s.MapRealUID {
-		/* some programs fail to connect to dbus session running as a different uid
-		so this workaround is introduced to map priv-side caller uid in container */
 		params.Uid = os.Getuid()
 		*uid = params.Uid
 		params.Gid = os.Getgid()
@@ -104,6 +101,7 @@ func newContainer(s *hst.ContainerConfig, os sys.State, prefix string, uid, gid
 	}
 
 	/* retrieve paths and hide them if they're made available in the sandbox;
+
 	this feature tries to improve user experience of permissive defaults, and
 	to warn about issues in custom configuration; it is NOT a security feature
 	and should not be treated as such, ALWAYS be careful with what you bind */