hst: reword and improve doc comments

This corrects minor mistakes in doc comments and adds them for undocumented constants.

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

7 files changed, 48 insertions, 39 deletions

diff --git a/hst/enablement.go b/hst/enablement.go
index deaacb9d..7a1056d1 100644
--- a/hst/enablement.go
+++ b/hst/enablement.go
@@ -11,14 +11,20 @@ import (
 type Enablement byte
 
 const (
+	// EWayland exposes a wayland pathname socket via security-context-v1.
 	EWayland Enablement = 1 << iota
+	// EX11 adds the target user via X11 ChangeHosts and exposes the X11 pathname socket.
 	EX11
+	// EDBus enables the per-container xdg-dbus-proxy daemon.
 	EDBus
+	// EPulse copies the PulseAudio cookie to [hst.PrivateTmp] and exposes the PulseAudio socket.
 	EPulse
 
+	// EM is a noop.
 	EM
 )
 
+// String returns a string representation of the flags set on [Enablement].
 func (e Enablement) String() string {
 	switch e {
 	case 0:
@@ -51,17 +57,17 @@ func (e Enablement) String() string {
 // NewEnablements returns the address of [Enablement] as [Enablements].
 func NewEnablements(e Enablement) *Enablements { return (*Enablements)(&e) }
 
-// enablementsJSON is the [json] representation of the [Enablement] bit field.
-type enablementsJSON struct {
+// Enablements is the [json] adapter for [Enablement].
+type Enablements Enablement
+
+// enablementsJSON is the [json] representation of [Enablements].
+type enablementsJSON = struct {
 	Wayland bool `json:"wayland,omitempty"`
 	X11     bool `json:"x11,omitempty"`
 	DBus    bool `json:"dbus,omitempty"`
 	Pulse   bool `json:"pulse,omitempty"`
 }
 
-// Enablements is the [json] adapter for [Enablement].
-type Enablements Enablement
-
 // Unwrap returns the underlying [Enablement].
 func (e *Enablements) Unwrap() Enablement {
 	if e == nil {
diff --git a/hst/fs.go b/hst/fs.go
index 07ed6b4a..926d6233 100644
--- a/hst/fs.go
+++ b/hst/fs.go
@@ -47,17 +47,16 @@ type Ops interface {
 	Etc(host *check.Absolute, prefix string) Ops
 }
 
-// ApplyState holds the address of [container.Ops] and any relevant application state.
+// ApplyState holds the address of [Ops] and any relevant application state.
 type ApplyState struct {
-	// AutoEtcPrefix is the prefix for [container.AutoEtcOp].
+	// AutoEtcPrefix is the prefix for [FSBind] in autoetc [FSBind.Special] condition.
 	AutoEtcPrefix string
 
 	Ops
 }
 
-var (
-	ErrFSNull = errors.New("unexpected null in mount point")
-)
+// ErrFSNull is returned by [json] on encountering a null [FilesystemConfig] value.
+var ErrFSNull = errors.New("unexpected null in mount point")
 
 // FSTypeError is returned when [ContainerConfig.Filesystem] contains an entry with invalid type.
 type FSTypeError string
@@ -90,7 +89,7 @@ func (f *FilesystemConfigJSON) Valid() bool {
 	return f != nil && f.FilesystemConfig != nil && f.FilesystemConfig.Valid()
 }
 
-// fsType holds the string representation of a [FilesystemConfig]'s concrete type.
+// fsType holds the string representation of the concrete type of [FilesystemConfig].
 type fsType struct {
 	Type string `json:"type"`
 }
diff --git a/hst/fsbind.go b/hst/fsbind.go
index f94e467b..bb1fc036 100644
--- a/hst/fsbind.go
+++ b/hst/fsbind.go
@@ -16,22 +16,23 @@ const FilesystemBind = "bind"
 
 // FSBind represents a host to container bind mount.
 type FSBind struct {
-	// mount point in container, same as Source if empty
+	// Pathname in the container mount namespace. Same as Source if nil.
 	Target *check.Absolute `json:"dst,omitempty"`
-	// host filesystem path to make available to the container
+	// Pathname in the init mount namespace. Must not be nil.
 	Source *check.Absolute `json:"src"`
-	// do not mount Target read-only
+	// Do not remount Target read-only.
+	// This has no effect if Source is mounted read-only in the init mount namespace.
 	Write bool `json:"write,omitempty"`
-	// do not disable device files on Target, implies Write
+	// Allow access to devices (special files) on Target, implies Write.
 	Device bool `json:"dev,omitempty"`
-	// create Source as a directory if it does not exist
+	// Create Source as a directory in the init mount namespace if it does not exist.
 	Ensure bool `json:"ensure,omitempty"`
-	// skip this mount point if Source does not exist
+	// Silently skip this mount point if Source does not exist in the init mount namespace.
 	Optional bool `json:"optional,omitempty"`
 
-	// enable special behaviour:
-	// for autoroot, Target must be set to [fhs.AbsRoot];
-	// for autoetc, Target must be set to [fhs.AbsEtc]
+	/* Enable special behaviour:
+	For autoroot: Target must be [fhs.Root].
+	For autoetc:  Target must be [fhs.Etc]. */
 	Special bool `json:"special,omitempty"`
 }
 
diff --git a/hst/fsephemeral.go b/hst/fsephemeral.go
index 631235b5..78c4a55a 100644
--- a/hst/fsephemeral.go
+++ b/hst/fsephemeral.go
@@ -15,13 +15,13 @@ const FilesystemEphemeral = "ephemeral"
 
 // FSEphemeral represents an ephemeral container mount point.
 type FSEphemeral struct {
-	// mount point in container
-	Target *check.Absolute `json:"dst,omitempty"`
-	// do not mount filesystem read-only
+	// Pathname in the container mount namespace.
+	Target *check.Absolute `json:"dst"`
+	// Do not mount filesystem read-only.
 	Write bool `json:"write,omitempty"`
-	// upper limit on the size of the filesystem
+	// Upper limit on the size of the filesystem.
 	Size int `json:"size,omitempty"`
-	// initial permission bits of the new filesystem
+	// Initial permission bits of the new filesystem.
 	Perm os.FileMode `json:"perm,omitempty"`
 }
 
diff --git a/hst/fslink.go b/hst/fslink.go
index 473506e6..2a1e3795 100644
--- a/hst/fslink.go
+++ b/hst/fslink.go
@@ -14,11 +14,11 @@ const FilesystemLink = "link"
 
 // FSLink represents a symlink in the container filesystem.
 type FSLink struct {
-	// link path in container
+	// Pathname in the container mount namespace.
 	Target *check.Absolute `json:"dst"`
-	// linkname the symlink points to
+	// Arbitrary linkname value store in the symlink.
 	Linkname string `json:"linkname"`
-	// whether to dereference linkname before creating the link
+	// Whether to treat Linkname as an absolute pathname and dereference before creating the link.
 	Dereference bool `json:"dereference,omitempty"`
 }
 
diff --git a/hst/fsoverlay.go b/hst/fsoverlay.go
index 689970df..de4e14dd 100644
--- a/hst/fsoverlay.go
+++ b/hst/fsoverlay.go
@@ -14,14 +14,14 @@ const FilesystemOverlay = "overlay"
 
 // FSOverlay represents an overlay mount point.
 type FSOverlay struct {
-	// mount point in container
+	// Pathname in the container mount namespace.
 	Target *check.Absolute `json:"dst"`
 
-	// any filesystem, does not need to be on a writable filesystem, must not be nil
+	// Any filesystem, does not need to be on a writable filesystem, must not be nil.
 	Lower []*check.Absolute `json:"lower"`
-	// the upperdir is normally on a writable filesystem, leave as nil to mount Lower readonly
+	// The upperdir is normally on a writable filesystem, leave as nil to mount Lower readonly.
 	Upper *check.Absolute `json:"upper,omitempty"`
-	// the workdir needs to be an empty directory on the same filesystem as Upper, must not be nil if Upper is populated
+	// The workdir needs to be an empty directory on the same filesystem as Upper, must not be nil if Upper is populated.
 	Work *check.Absolute `json:"work,omitempty"`
 }
 
diff --git a/hst/hst.go b/hst/hst.go
index 208b395a..11e91e7b 100644
--- a/hst/hst.go
+++ b/hst/hst.go
@@ -12,9 +12,12 @@ import (
 
 // An AppError is returned while starting an app according to [hst.Config].
 type AppError struct {
-	Step string
-	Err  error
-	Msg  string
+	// A user-facing description of where the error occurred.
+	Step string `json:"step"`
+	// The underlying error value.
+	Err error
+	// An arbitrary error message, overriding the return value of Message if not empty.
+	Msg string `json:"message,omitempty"`
 }
 
 func (e *AppError) Error() string { return e.Err.Error() }
@@ -38,13 +41,13 @@ func (e *AppError) Message() string {
 
 // Paths contains environment-dependent paths used by hakurei.
 type Paths struct {
-	// temporary directory returned by [os.TempDir] (usually `/tmp`)
+	// Temporary directory returned by [os.TempDir], usually equivalent to [fhs.AbsTmp].
 	TempDir *check.Absolute `json:"temp_dir"`
-	// path to shared directory (usually `/tmp/hakurei.%d`, [Info.User])
+	// Shared directory specific to the hsu userid, usually (`/tmp/hakurei.%d`, [Info.User]).
 	SharePath *check.Absolute `json:"share_path"`
-	// XDG_RUNTIME_DIR value (usually `/run/user/%d`, uid)
+	// Checked XDG_RUNTIME_DIR value, usually (`/run/user/%d`, uid).
 	RuntimePath *check.Absolute `json:"runtime_path"`
-	// application runtime directory (usually `/run/user/%d/hakurei`)
+	// Shared directory specific to the hsu userid located in RuntimePath, usually (`/run/user/%d/hakurei`, uid).
 	RunDirPath *check.Absolute `json:"run_dir_path"`
 }