hst/config: update doc comments

Some information here are horribly out of date. This change updates and improves all doc comments.

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

hst/config.go

@@ -18,86 +18,91 @@ const (
 	MaxWaitDelay = 30 * time.Second
 )
 
-// Config is used to seal an app implementation.
 type (
+	// Config configures an application container, implemented in internal/app.
 	Config struct {
-		// reverse-DNS style arbitrary identifier string from config;
+		// Reverse-DNS style configured arbitrary identifier string.
-		// passed to wayland security-context-v1 as application ID
+		// Passed to wayland security-context-v1 and used as part of defaults in dbus session proxy.
-		// and used as part of defaults in dbus session proxy
 		ID string `json:"id"`
 
-		// absolute path to executable file
+		// Pathname to executable file in the container filesystem.
 		Path *container.Absolute `json:"path,omitempty"`
-		// final args passed to container init
+		// Final args passed to the initial program.
 		Args []string `json:"args"`
 
-		// system services to make available in the container
+		// System services to make available in the container.
 		Enablements *Enablements `json:"enablements,omitempty"`
 
-		// session D-Bus proxy configuration;
+		// Session D-Bus proxy configuration.
-		// nil makes session bus proxy assume built-in defaults
+		// If set to nil, session bus proxy assume built-in defaults.
 		SessionBus *dbus.Config `json:"session_bus,omitempty"`
-		// system D-Bus proxy configuration;
+		// System D-Bus proxy configuration.
-		// nil disables system bus proxy
+		// If set to nil, system bus proxy is disabled.
 		SystemBus *dbus.Config `json:"system_bus,omitempty"`
-		// direct access to wayland socket; when this gets set no attempt is made to attach security-context-v1
+		// Direct access to wayland socket, no attempt is made to attach security-context-v1
-		// and the bare socket is mounted to the sandbox
+		// and the bare socket is made available to the container.
 		DirectWayland bool `json:"direct_wayland,omitempty"`
 
-		// passwd username in container, defaults to passwd name of target uid or chronos
+		// 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"`
-		// absolute path to shell
+		// Pathname of shell in the container filesystem to use for the emulated user.
 		Shell *container.Absolute `json:"shell"`
-		// directory to enter and use as home in the container mount namespace
+		// Directory in the container filesystem to enter and use as the home directory of the emulated user.
 		Home *container.Absolute `json:"home"`
 
-		// extra acl ops to perform before setuid
+		// Extra acl update ops to perform before setuid.
 		ExtraPerms []*ExtraPermConfig `json:"extra_perms,omitempty"`
 
-		// numerical application id, used for init user namespace credentials
+		// Numerical application id, passed to hsu, used to derive init user namespace credentials.
 		Identity int `json:"identity"`
-		// list of supplementary groups inherited by container processes
+		// Init user namespace supplementary groups inherited by all container processes.
 		Groups []string `json:"groups"`
 
-		// abstract container configuration baseline
+		// High level configuration applied to the underlying [container.Params].
 		Container *ContainerConfig `json:"container"`
 	}
 
-	// ContainerConfig describes the container configuration baseline to which the app implementation adds upon.
+	// ContainerConfig describes the container configuration to be applied to an underlying [container.Params].
 	ContainerConfig struct {
-		// container hostname
+		// Container UTS namespace hostname.
 		Hostname string `json:"hostname,omitempty"`
 
-		// duration to wait for after interrupting a container's initial process in nanoseconds;
+		// Duration in nanoseconds to wait for after interrupting the initial process.
-		// a negative value causes the container to be terminated immediately on cancellation
+		// Defaults to [DefaultWaitDelay] if less than or equals to zero,
+		// or [MaxWaitDelay] if greater than [MaxWaitDelay].
 		WaitDelay time.Duration `json:"wait_delay,omitempty"`
 
-		// disable project-specific filter extensions
+		// Emit Flatpak-compatible seccomp filter programs.
 		SeccompCompat bool `json:"seccomp_compat,omitempty"`
-		// allow ptrace and friends
+		// Allow ptrace and friends.
 		Devel bool `json:"devel,omitempty"`
-		// allow userns creation in container
+		// Allow userns creation and container setup syscalls.
 		Userns bool `json:"userns,omitempty"`
-		// share host net namespace
+		// Share host net namespace.
 		HostNet bool `json:"host_net,omitempty"`
-		// share abstract unix socket scope
+		// Share abstract unix socket scope.
 		HostAbstract bool `json:"host_abstract,omitempty"`
-		// allow dangerous terminal I/O
+		// Allow dangerous terminal I/O (faking input).
 		Tty bool `json:"tty,omitempty"`
-		// allow multiarch
+		// Allow multiarch.
 		Multiarch bool `json:"multiarch,omitempty"`
 
-		// initial process environment variables
+		// Initial process environment variables.
 		Env map[string]string `json:"env"`
-		// 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,
+		/* Map target user uid to privileged user uid in the container user namespace.
-		// this option works around it by mapping priv-side caller uid in container
+
+		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
+		// Mount /dev/ from the init mount namespace as-is in the container mount namespace.
 		Device bool `json:"device,omitempty"`
-		// 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. */
 		Filesystem []FilesystemConfigJSON `json:"filesystem"`
 	}
 )