From e082cfb3b8f8226067078cc410e4997fd1cf14df Mon Sep 17 00:00:00 2001 From: Luke Shumaker Date: Thu, 16 Mar 2023 18:45:45 -0400 Subject: tree-wide: Ensure that all existing method doc comments follow the expected format --- .golangci.yml | 1 - lib/btrfs/btrfsitem/items.go | 6 +++++- lib/btrfs/btrfsprim/key.go | 5 ++++- lib/btrfs/btrfstree/path.go | 7 ++++--- lib/btrfs/btrfstree/types_node.go | 2 ++ lib/containers/ordered.go | 8 ++++---- lib/slices/sliceutil.go | 8 +++++--- lib/textui/log.go | 4 ++-- 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: -- cgit v1.1-4-g5e80