tree-wide: Ensure that all existing method doc comments follow the expected format

8 files changed, 26 insertions, 15 deletions

diff --git a/.golangci.yml b/.golangci.yml
index 07ff58d..2117d0f 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
-      - "-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:
     case:
diff --git a/lib/btrfs/btrfsitem/items.go b/lib/btrfs/btrfsitem/items.go
index dd14fb8..a730447 100644
--- a/lib/btrfs/btrfsitem/items.go
+++ b/lib/btrfs/btrfsitem/items.go
@@ -58,7 +58,11 @@ func (o *Error) UnmarshalBinary(dat []byte) (int, error) {
 	return len(dat), nil
 }
 
-// Rather than returning a separate error value, return an Error item.
+// UnmarshalItem consumes the byte slice `dat`, unmarshaling it in to
+// the item type specified by `key`.
+//
+// If there is an error, rather than returning a separate error value,
+// return an Error item.
 func UnmarshalItem(key btrfsprim.Key, csumType btrfssum.CSumType, dat []byte) Item {
 	var gotyp reflect.Type
 	if key.ItemType == UNTYPED_KEY {
diff --git a/lib/btrfs/btrfsprim/key.go b/lib/btrfs/btrfsprim/key.go
index b07cc8c..2930782 100644
--- a/lib/btrfs/btrfsprim/key.go
+++ b/lib/btrfs/btrfsprim/key.go
@@ -21,7 +21,10 @@ type Key struct {
 
 const MaxOffset uint64 = math.MaxUint64
 
-// mimics print-tree.c:btrfs_print_key()
+// Format returns a human-friendly string representation of the Key,
+// according to which tree it appears in.
+//
+// The formatting of the key mimics print-tree.c:btrfs_print_key().
 func (key Key) Format(tree ObjID) string {
 	switch tree {
 	case UUID_TREE_OBJECTID:
diff --git a/lib/btrfs/btrfstree/path.go b/lib/btrfs/btrfstree/path.go
index 9b1a5c7..dc2fc1d 100644
--- a/lib/btrfs/btrfstree/path.go
+++ b/lib/btrfs/btrfstree/path.go
@@ -128,9 +128,10 @@ func (path TreePath) Parent() TreePath {
 	return path[:len(path)-1]
 }
 
-// path.Node(x) is like &path[x], but negative values of x move down
-// from the end of path (similar to how lists work in many other
-// languages, such as Python).
+// Node is returns an element from the path; `path.Node(x)` is like
+// `&path[x]`, but negative values of x move down from the end of path
+// (similar to how lists work in many other languages, such as
+// Python).
 func (path TreePath) Node(x int) *TreePathElem {
 	if x < 0 {
 		x += len(path)
diff --git a/lib/btrfs/btrfstree/types_node.go b/lib/btrfs/btrfstree/types_node.go
index 150539d..c770fe8 100644
--- a/lib/btrfs/btrfstree/types_node.go
+++ b/lib/btrfs/btrfstree/types_node.go
@@ -456,6 +456,8 @@ func newNodeRef[Addr ~int64]() *diskio.Ref[Addr, Node] {
 	return (*diskio.Ref[Addr, Node])(unsafe.Pointer(ret)) //nolint:gosec // I know it's unsafe.
 }
 
+// ReadNode reads a node from the given file.
+//
 // It is possible that both a non-nil diskio.Ref and an error are
 // returned.  The error returned (if non-nil) is always of type
 // *NodeError[Addr].  Notable errors that may be inside of the
diff --git a/lib/containers/ordered.go b/lib/containers/ordered.go
index 1ebc17e..1289b45 100644
--- a/lib/containers/ordered.go
+++ b/lib/containers/ordered.go
@@ -12,7 +12,7 @@ type _Ordered[T any] interface {
 	Compare(T) int
 }
 
-// An Ordered[T] is a type that has a
+// An Ordered is a type that has a
 //
 //	func (a T) Compare(b T) int
 //
@@ -36,10 +36,10 @@ type NativeOrdered[T constraints.Ordered] struct {
 	Val T
 }
 
-// NativeCompare[T] implements the Ordered[T] Compare operation for
+// NativeCompare implements the Ordered[T] Compare operation for
 // natively-ordered (integer types, float types, and string types).
-// While this operation be conceptualized as subtration,
-// NativeCompare[T] is careful to avoid integer overflow.
+// While this operation be conceptualized as subtration, NativeCompare
+// is careful to avoid integer overflow.
 func NativeCompare[T constraints.Ordered](a, b T) int {
 	switch {
 	case a < b:
diff --git a/lib/slices/sliceutil.go b/lib/slices/sliceutil.go
index 9fe5be4..b8823d3 100644
--- a/lib/slices/sliceutil.go
+++ b/lib/slices/sliceutil.go
@@ -95,7 +95,7 @@ func max(a, b int) int {
 	return b
 }
 
-// Search the slice for a value for which `fn(slice[i]) = 0`.
+// Search searches the slice for a value for which `fn(slice[i]) = 0`.
 //
 //	: + + + 0 0 0 - - -
 //	:       ^ ^ ^
@@ -123,7 +123,8 @@ func Search[T any](slice []T, fn func(T) int) (int, bool) {
 	return 0, false
 }
 
-// Search the slice for the left-most value for which `fn(slice[i]) = 0`.
+// SearchLowest searches the slice for the left-most value for which
+// `fn(slice[i]) = 0`.
 //
 //	: + + + 0 0 0 - - -
 //	:       ^
@@ -153,7 +154,8 @@ func SearchLowest[T any](slice []T, fn func(T) int) (int, bool) {
 	return firstGood, true
 }
 
-// Search the slice for the right-most value for which `fn(slice[i]) = 0`.
+// SearchHighest searches the slice for the right-most value for which
+// `fn(slice[i]) = 0`.
 //
 //	: + + + 0 0 0 - - -
 //	:           ^
diff --git a/lib/textui/log.go b/lib/textui/log.go
index 0a10ef6..6cf9abe 100644
--- a/lib/textui/log.go
+++ b/lib/textui/log.go
@@ -37,7 +37,7 @@ var _ pflag.Value = (*LogLevelFlag)(nil)
 // Type implements pflag.Value.
 func (lvl *LogLevelFlag) Type() string { return "loglevel" }
 
-// Type implements pflag.Value.
+// Set implements pflag.Value.
 func (lvl *LogLevelFlag) Set(str string) error {
 	switch strings.ToLower(str) {
 	case "error":
@@ -56,7 +56,7 @@ func (lvl *LogLevelFlag) Set(str string) error {
 	return nil
 }
 
-// Type implements pflag.Value.
+// String implements fmt.Stringer (and pflag.Value).
 func (lvl *LogLevelFlag) String() string {
 	switch lvl.Level {
 	case dlog.LogLevelError: