tree-wide: Ensure that all packages have a doc comment

23 files changed, 63 insertions, 6 deletions

diff --git a/.golangci.yml b/.golangci.yml
index 7ba2e5a..07ff58d 100644
--- a/.golangci.yml
+++ b/.golangci.yml
@@ -89,7 +89,6 @@ linters-settings:
     checks:
       - "all"
       - "-ST1003" # CONST_VAL names for consistency with other btrfs code
-      - "-ST1000" # TODO: get this to pass: "at least one file in a package should have a package comment"
       - "-ST1020" # TODO: get this to pass: "comment on exported method XXX should be of the form "XXX ...""
       - "-ST1021" # TODO: get this to pass: "comment on exported type XXX should be of the form "XXX ...""
   tagliatelle:
diff --git a/cmd/btrfs-rec/inspect/dumptrees/print_tree.go b/cmd/btrfs-rec/inspect/dumptrees/print_tree.go
index a0a3d46..a8c2adf 100644
--- a/cmd/btrfs-rec/inspect/dumptrees/print_tree.go
+++ b/cmd/btrfs-rec/inspect/dumptrees/print_tree.go
@@ -2,6 +2,8 @@
 //
 // SPDX-License-Identifier: GPL-2.0-or-later
 
+// Package dumptrees is the guts of the `btrfs-rec inspect dump-trees`
+// command, which is a clone of `btrfs inspect-internal dump-tree`.
 package dumptrees
 
 import (
diff --git a/cmd/btrfs-rec/inspect/mount/mount.go b/cmd/btrfs-rec/inspect/mount/mount.go
index da0bbb6..01d667f 100644
--- a/cmd/btrfs-rec/inspect/mount/mount.go
+++ b/cmd/btrfs-rec/inspect/mount/mount.go
@@ -2,6 +2,9 @@
 //
 // SPDX-License-Identifier: GPL-2.0-or-later
 
+// Package mount is the guts of the `btrfs-rec inspect mount` command,
+// which mounts the filesystem read-only using FUSE; providing better
+// tolerance of filesystem corruption than the in-kernel btrfs driver.
 package mount
 
 import (
diff --git a/cmd/btrfs-rec/inspect/rebuildmappings/process.go b/cmd/btrfs-rec/inspect/rebuildmappings/process.go
index 7ce3748..a93b697 100644
--- a/cmd/btrfs-rec/inspect/rebuildmappings/process.go
+++ b/cmd/btrfs-rec/inspect/rebuildmappings/process.go
@@ -2,6 +2,9 @@
 //
 // SPDX-License-Identifier: GPL-2.0-or-later
 
+// Package rebuildmappings is the guts of the `btrfs-rec inspect
+// rebuild-mappings` command, which rebuilds broken
+// chunk/dev-extent/blockgroup trees.
 package rebuildmappings
 
 import (
diff --git a/cmd/btrfs-rec/inspect/rebuildtrees/rebuild.go b/cmd/btrfs-rec/inspect/rebuildtrees/rebuild.go
index 708b504..364dfa0 100644
--- a/cmd/btrfs-rec/inspect/rebuildtrees/rebuild.go
+++ b/cmd/btrfs-rec/inspect/rebuildtrees/rebuild.go
@@ -2,6 +2,10 @@
 //
 // SPDX-License-Identifier: GPL-2.0-or-later
 
+// Package rebuildtrees is the guts of the `btrfs-rec inspect
+// rebuild-trees` command, which rebuilds broken trees, but requires
+// already-functioning chunk/dev-extent/blockgroup trees.
+// chunk/dev-extent/blockgroup trees.
 package rebuildtrees
 
 import (
diff --git a/lib/binstruct/binutil/binutil.go b/lib/binstruct/binutil/binutil.go
index 684237f..a5c65b5 100644
--- a/lib/binstruct/binutil/binutil.go
+++ b/lib/binstruct/binutil/binutil.go
@@ -1,7 +1,9 @@
-// Copyright (C) 2022  Luke Shumaker <lukeshu@lukeshu.com>
+// Copyright (C) 2022-2023  Luke Shumaker <lukeshu@lukeshu.com>
 //
 // SPDX-License-Identifier: GPL-2.0-or-later
 
+// Package binutil provides utilities for implementing the interfaces
+// consumed by binstruct.
 package binutil
 
 import (
diff --git a/lib/binstruct/unmarshal.go b/lib/binstruct/unmarshal.go
index eae4b84..41aab9c 100644
--- a/lib/binstruct/unmarshal.go
+++ b/lib/binstruct/unmarshal.go
@@ -2,6 +2,9 @@
 //
 // SPDX-License-Identifier: GPL-2.0-or-later
 
+// Package binstruct implements simple struct-tag-based conversion
+// between Go structures and binary on-disk representations of that
+// data.
 package binstruct
 
 import (
diff --git a/lib/btrfs/btrfsitem/items.go b/lib/btrfs/btrfsitem/items.go
index 49d421f..dd14fb8 100644
--- a/lib/btrfs/btrfsitem/items.go
+++ b/lib/btrfs/btrfsitem/items.go
@@ -2,6 +2,8 @@
 //
 // SPDX-License-Identifier: GPL-2.0-or-later
 
+// Package btrfsitem contains the definitions of all "items" that may
+// be stored in a btrfs tree.
 package btrfsitem
 
 import (
diff --git a/lib/btrfs/btrfsprim/misc.go b/lib/btrfs/btrfsprim/misc.go
index 38290d6..43ba306 100644
--- a/lib/btrfs/btrfsprim/misc.go
+++ b/lib/btrfs/btrfsprim/misc.go
@@ -2,6 +2,8 @@
 //
 // SPDX-License-Identifier: GPL-2.0-or-later
 
+// Package btrfsprim contains primitive btrfs datatypes, that all
+// other btrfs sub-packages may make use of.
 package btrfsprim
 
 import (
diff --git a/lib/btrfs/btrfssum/csum.go b/lib/btrfs/btrfssum/csum.go
index 157371e..341eade 100644
--- a/lib/btrfs/btrfssum/csum.go
+++ b/lib/btrfs/btrfssum/csum.go
@@ -2,6 +2,8 @@
 //
 // SPDX-License-Identifier: GPL-2.0-or-later
 
+// Package btrfssum contains the checksum types and algorithms that
+// btrfs uses.
 package btrfssum
 
 import (
diff --git a/lib/btrfs/btrfstree/btree.go b/lib/btrfs/btrfstree/btree.go
index 4c10ffa..89d4f9d 100644
--- a/lib/btrfs/btrfstree/btree.go
+++ b/lib/btrfs/btrfstree/btree.go
@@ -2,6 +2,8 @@
 //
 // SPDX-License-Identifier: GPL-2.0-or-later
 
+// Package btrfstree contains core b+-tree implementation and
+// interfaces.
 package btrfstree
 
 import (
diff --git a/lib/btrfs/btrfsvol/lvm.go b/lib/btrfs/btrfsvol/lvm.go
index 51e2263..3834345 100644
--- a/lib/btrfs/btrfsvol/lvm.go
+++ b/lib/btrfs/btrfsvol/lvm.go
@@ -2,6 +2,8 @@
 //
 // SPDX-License-Identifier: GPL-2.0-or-later
 
+// Package btrfsvol contains core logical-volume-management layer of
+// btrfs.
 package btrfsvol
 
 import (
diff --git a/lib/btrfs/io1_pv.go b/lib/btrfs/io1_pv.go
index 72d33f5..3b13f73 100644
--- a/lib/btrfs/io1_pv.go
+++ b/lib/btrfs/io1_pv.go
@@ -2,6 +2,8 @@
 //
 // SPDX-License-Identifier: GPL-2.0-or-later
 
+// Package btrfs (and its sub-packages) are the core implementation of
+// the btrfs filesystem.
 package btrfs
 
 import (
diff --git a/lib/btrfscheck/graph.go b/lib/btrfscheck/graph.go
index ea51818..ae6d1ec 100644
--- a/lib/btrfscheck/graph.go
+++ b/lib/btrfscheck/graph.go
@@ -2,6 +2,8 @@
 //
 // SPDX-License-Identifier: GPL-2.0-or-later
 
+// Package btrfscheck implements userspace utilities for checking
+// btrfs filesystems.
 package btrfscheck
 
 import (
diff --git a/lib/btrfsutil/doc.go b/lib/btrfsutil/doc.go
new file mode 100644
index 0000000..4d00cb3
--- /dev/null
+++ b/lib/btrfsutil/doc.go
@@ -0,0 +1,7 @@
+// Copyright (C) 2023  Luke Shumaker <lukeshu@lukeshu.com>
+//
+// SPDX-License-Identifier: GPL-2.0-or-later
+
+// Package btrfsutil implements userspace utilities for working with
+// btrfs filesystems.
+package btrfsutil
diff --git a/lib/containers/doc.go b/lib/containers/doc.go
new file mode 100644
index 0000000..1725e31
--- /dev/null
+++ b/lib/containers/doc.go
@@ -0,0 +1,7 @@
+// Copyright (C) 2023  Luke Shumaker <lukeshu@lukeshu.com>
+//
+// SPDX-License-Identifier: GPL-2.0-or-later
+
+// Package containers implements generic (type-parameterized) datatype
+// containers.
+package containers
diff --git a/lib/diskio/file_iface.go b/lib/diskio/file_iface.go
index 206db0c..d26ffcc 100644
--- a/lib/diskio/file_iface.go
+++ b/lib/diskio/file_iface.go
@@ -1,7 +1,8 @@
-// Copyright (C) 2022  Luke Shumaker <lukeshu@lukeshu.com>
+// Copyright (C) 2022-2023  Luke Shumaker <lukeshu@lukeshu.com>
 //
 // SPDX-License-Identifier: GPL-2.0-or-later
 
+// Package diskio implements utilities for working with disk I/O.
 package diskio
 
 import (
diff --git a/lib/fmtutil/fmt.go b/lib/fmtutil/fmt.go
index b310eb6..bad4a30 100644
--- a/lib/fmtutil/fmt.go
+++ b/lib/fmtutil/fmt.go
@@ -1,7 +1,9 @@
-// Copyright (C) 2022  Luke Shumaker <lukeshu@lukeshu.com>
+// Copyright (C) 2022-2023  Luke Shumaker <lukeshu@lukeshu.com>
 //
 // SPDX-License-Identifier: GPL-2.0-or-later
 
+// Package fmtutil provides utilities for implementing the interfaces
+// consumed by the "fmt" package.
 package fmtutil
 
 import (
diff --git a/lib/maps/maputil.go b/lib/maps/maputil.go
index aeebe12..d409e70 100644
--- a/lib/maps/maputil.go
+++ b/lib/maps/maputil.go
@@ -1,7 +1,9 @@
-// Copyright (C) 2022  Luke Shumaker <lukeshu@lukeshu.com>
+// Copyright (C) 2022-2023  Luke Shumaker <lukeshu@lukeshu.com>
 //
 // SPDX-License-Identifier: GPL-2.0-or-later
 
+// Package maps implements generic (type-parameterized) utilities for
+// working with simple Go maps.
 package maps
 
 import (
diff --git a/lib/profile/profile.go b/lib/profile/profile.go
index 27c7e61..0910e5c 100644
--- a/lib/profile/profile.go
+++ b/lib/profile/profile.go
@@ -2,6 +2,8 @@
 //
 // SPDX-License-Identifier: GPL-2.0-or-later
 
+// Package profile implements a uniform interface for getting
+// profiling information from the Go runtime.
 package profile
 
 import (
diff --git a/lib/slices/sliceutil.go b/lib/slices/sliceutil.go
index 567f9ec..9fe5be4 100644
--- a/lib/slices/sliceutil.go
+++ b/lib/slices/sliceutil.go
@@ -1,7 +1,9 @@
-// Copyright (C) 2022  Luke Shumaker <lukeshu@lukeshu.com>
+// Copyright (C) 2022-2023  Luke Shumaker <lukeshu@lukeshu.com>
 //
 // SPDX-License-Identifier: GPL-2.0-or-later
 
+// Package slices implements generic (type-parameterized) utilities
+// for working with simple Go slices.
 package slices
 
 import (
diff --git a/lib/streamio/runescanner.go b/lib/streamio/runescanner.go
index 451f32f..947efeb 100644
--- a/lib/streamio/runescanner.go
+++ b/lib/streamio/runescanner.go
@@ -2,6 +2,8 @@
 //
 // SPDX-License-Identifier: GPL-2.0-or-later
 
+// Package streamio implements utilities for working with streaming
+// I/O.
 package streamio
 
 import (
diff --git a/lib/textui/text.go b/lib/textui/text.go
index c0a3c5e..538bac2 100644
--- a/lib/textui/text.go
+++ b/lib/textui/text.go
@@ -2,6 +2,8 @@
 //
 // SPDX-License-Identifier: GPL-2.0-or-later
 
+// Package textui implements utilities for emitting human-friendly
+// text on stdout and stderr.
 package textui
 
 import (