hst: improve doc comments

These now read a lot better both in source and on pkgsite.

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

1 files changed, 33 insertions, 18 deletions

diff --git a/hst/container.go b/hst/container.go
index f9cc95ed..8696d85b 100644
--- a/hst/container.go
+++ b/hst/container.go
@@ -16,18 +16,20 @@ const PrivateTmp = "/.hakurei"
 var AbsPrivateTmp = check.MustAbs(PrivateTmp)
 
 const (
-	// WaitDelayDefault is used when WaitDelay has its zero value.
+	// WaitDelayDefault is used when WaitDelay has the zero value.
 	WaitDelayDefault = 5 * time.Second
-	// WaitDelayMax is used if WaitDelay exceeds its value.
+	// WaitDelayMax is used when WaitDelay exceeds its value.
 	WaitDelayMax = 30 * time.Second
 )
 
 const (
 	// ExitFailure is returned if the container fails to start.
 	ExitFailure = iota + 1
-	// ExitCancel is returned if the container is terminated by a shim-directed signal which cancels its context.
+	// ExitCancel is returned if the container is terminated by a shim-directed
+	// signal which cancels its context.
 	ExitCancel
-	// ExitOrphan is returned when the shim is orphaned before priv side delivers a signal.
+	// ExitOrphan is returned when the shim is orphaned before priv side process
+	// delivers a signal.
 	ExitOrphan
 
 	// ExitRequest is returned when the priv side process requests shim exit.
@@ -38,10 +40,12 @@ const (
 type Flags uintptr
 
 const (
-	// FMultiarch unblocks syscalls required for multiarch to work on applicable targets.
+	// FMultiarch unblocks system calls required for multiarch to work on
+	// multiarch-enabled targets (amd64, arm64).
 	FMultiarch Flags = 1 << iota
 
-	// FSeccompCompat changes emitted seccomp filter programs to be identical to that of Flatpak.
+	// FSeccompCompat changes emitted seccomp filter programs to be identical to
+	// that of Flatpak in enabled rulesets.
 	FSeccompCompat
 	// FDevel unblocks ptrace and friends.
 	FDevel
@@ -54,12 +58,15 @@ const (
 	// FTty unblocks dangerous terminal I/O (faking input).
 	FTty
 
-	// FMapRealUID maps the target user uid to the privileged user uid in the container 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.
+	// FMapRealUID maps the target user uid to the privileged user uid in the
+	// container 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.
 	FMapRealUID
 
-	// FDevice mount /dev/ from the init mount namespace as-is in the container mount namespace.
+	// FDevice mount /dev/ from the init mount namespace as is in the container
+	// mount namespace.
 	FDevice
 
 	// FShareRuntime shares XDG_RUNTIME_DIR between containers under the same identity.
@@ -112,30 +119,37 @@ func (flags Flags) String() string {
 	}
 }
 
-// ContainerConfig describes the container configuration to be applied to an underlying [container].
+// ContainerConfig describes the container configuration to be applied to an
+// underlying [container]. It is validated by [Config.Validate].
 type ContainerConfig struct {
 	// Container UTS namespace hostname.
 	Hostname string `json:"hostname,omitempty"`
 
 	// Duration in nanoseconds to wait for after interrupting the initial process.
-	// Defaults to [WaitDelayDefault] if zero, or [WaitDelayMax] if greater than [WaitDelayMax].
-	// Values lesser than zero is equivalent to zero, bypassing [WaitDelayDefault].
+	//
+	// Defaults to [WaitDelayDefault] if zero, or [WaitDelayMax] if greater than
+	// [WaitDelayMax]. Values lesser than zero is equivalent to zero, bypassing
+	// [WaitDelayDefault].
 	WaitDelay time.Duration `json:"wait_delay,omitempty"`
 
 	// Initial process environment variables.
 	Env map[string]string `json:"env"`
 
-	/* Container mount points.
-
-	If the first element targets /, it is inserted early and excluded from path hiding. */
+	// Container mount points.
+	//
+	// If the first element targets /, it is inserted early and excluded from
+	// path hiding. Otherwise, an anonymous instance of tmpfs is set up on /.
 	Filesystem []FilesystemConfigJSON `json:"filesystem"`
 
-	// String used as the username of the emulated user, validated against the default NAME_REGEX from adduser.
+	// String used as the username of the emulated user, validated against the
+	// default NAME_REGEX from adduser.
+	//
 	// Defaults to passwd name of target uid or chronos.
 	Username string `json:"username,omitempty"`
 	// Pathname of shell in the container filesystem to use for the emulated user.
 	Shell *check.Absolute `json:"shell"`
-	// Directory in the container filesystem to enter and use as the home directory of the emulated user.
+	// Directory in the container filesystem to enter and use as the home
+	// directory of the emulated user.
 	Home *check.Absolute `json:"home"`
 
 	// Pathname to executable file in the container filesystem.
@@ -148,6 +162,7 @@ type ContainerConfig struct {
 }
 
 // ContainerConfigF is [ContainerConfig] stripped of its methods.
+//
 // The [ContainerConfig.Flags] field does not survive a [json] round trip.
 type ContainerConfigF ContainerConfig