container: improve documentation

This change removes inconsistencies collected over time in this package.

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

container/vfs/mangle.go

@@ -2,6 +2,8 @@ package vfs
 
 import "strings"
 
+// Unmangle reverses mangling of strings done by the kernel. Its behaviour is
+// consistent with the equivalent function in util-linux.
 func Unmangle(s string) string {
 	if !strings.ContainsRune(s, '\\') {
 		return s

container/vfs/mountinfo.go

@@ -24,6 +24,7 @@ var (
 	ErrMountInfoSep    = errors.New("bad optional fields separator")
 )
 
+// A DecoderError describes a nonrecoverable error decoding a mountinfo stream.
 type DecoderError struct {
 	Op   string
 	Line int
@@ -51,7 +52,8 @@ func (e *DecoderError) Error() string {
 }
 
 type (
-	// A MountInfoDecoder reads and decodes proc_pid_mountinfo(5) entries from an input stream.
+	// A MountInfoDecoder reads and decodes proc_pid_mountinfo(5) entries from
+	// an input stream.
 	MountInfoDecoder struct {
 		s *bufio.Scanner
 		m *MountInfo
@@ -72,13 +74,16 @@ type (
 	MountInfoEntry struct {
 		// mount ID: a unique ID for the mount (may be reused after umount(2)).
 		ID int `json:"id"`
-		// parent ID: the ID of the parent mount (or of self for the root of this mount namespace's mount tree).
+		// parent ID: the ID of the parent mount (or of self for the root of
+		// this mount namespace's mount tree).
 		Parent int `json:"parent"`
 		// major:minor: the value of st_dev for files on this filesystem (see stat(2)).
 		Devno DevT `json:"devno"`
-		// root: the pathname of the directory in the filesystem which forms the root of this mount.
+		// root: the pathname of the directory in the filesystem which forms the
+		// root of this mount.
 		Root string `json:"root"`
-		// mount point: the pathname of the mount point relative to the process's root directory.
+		// mount point: the pathname of the mount point relative to the
+		// process's root directory.
 		Target string `json:"target"`
 		// mount options: per-mount options (see mount(2)).
 		VfsOptstr string `json:"vfs_optstr"`
@@ -126,7 +131,8 @@ func (e *MountInfoEntry) Flags() (flags uintptr, unmatched []string) {
 
 // NewMountInfoDecoder returns a new decoder that reads from r.
 //
-// The decoder introduces its own buffering and may read data from r beyond the mountinfo entries requested.
+// The decoder introduces its own buffering and may read data from r beyond the
+// mountinfo entries requested.
 func NewMountInfoDecoder(r io.Reader) *MountInfoDecoder {
 	return &MountInfoDecoder{s: bufio.NewScanner(r)}
 }
@@ -271,6 +277,8 @@ func parseMountInfoLine(s string, ent *MountInfoEntry) error {
 	return nil
 }
 
+// EqualWithIgnore compares to [MountInfoEntry] values, ignoring fields that
+// compare equal to ignore.
 func (e *MountInfoEntry) EqualWithIgnore(want *MountInfoEntry, ignore string) bool {
 	return (e.ID == want.ID || want.ID == -1) &&
 		(e.Parent == want.Parent || want.Parent == -1) &&
@@ -284,6 +292,8 @@ func (e *MountInfoEntry) EqualWithIgnore(want *MountInfoEntry, ignore string) bo
 		(e.FsOptstr == want.FsOptstr || want.FsOptstr == ignore)
 }
 
+// String returns a user-facing representation of a [MountInfoEntry]. It fits
+// roughly into the mountinfo format, but without mangling.
 func (e *MountInfoEntry) String() string {
 	return fmt.Sprintf("%d %d %d:%d %s %s %s %s %s %s %s",
 		e.ID, e.Parent, e.Devno[0], e.Devno[1], e.Root, e.Target, e.VfsOptstr,

container/vfs/unfold.go

@@ -6,6 +6,7 @@ import (
 	"strings"
 )
 
+// UnfoldTargetError is a pathname that never appeared in a mount hierarchy.
 type UnfoldTargetError string
 
 func (e UnfoldTargetError) Error() string {
@@ -27,6 +28,7 @@ func (n *MountInfoNode) Collective() iter.Seq[*MountInfoNode] {
 	return func(yield func(*MountInfoNode) bool) { n.visit(yield) }
 }
 
+// visit recursively visits all visible mountinfo nodes.
 func (n *MountInfoNode) visit(yield func(*MountInfoNode) bool) bool {
 	if !n.Covered && !yield(n) {
 		return false