From e082cfb3b8f8226067078cc410e4997fd1cf14df Mon Sep 17 00:00:00 2001
From: Luke Shumaker <lukeshu@lukeshu.com>
Date: Thu, 16 Mar 2023 18:45:45 -0400
Subject: tree-wide: Ensure that all existing method doc comments follow the
 expected format

---
 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 ++
 4 files changed, 15 insertions(+), 5 deletions(-)

(limited to 'lib/btrfs')

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
-- 
cgit v1.2.3-54-g00ecf