From 2ee7091933d2c07338dfb4699ce5665951b47afd Mon Sep 17 00:00:00 2001 From: Luke Shumaker Date: Thu, 16 Mar 2023 18:38:11 -0400 Subject: tree-wide: Ensure that all packages have a doc comment --- .golangci.yml | 1 - cmd/btrfs-rec/inspect/dumptrees/print_tree.go | 2 ++ cmd/btrfs-rec/inspect/mount/mount.go | 3 +++ cmd/btrfs-rec/inspect/rebuildmappings/process.go | 3 +++ cmd/btrfs-rec/inspect/rebuildtrees/rebuild.go | 4 ++++ lib/binstruct/binutil/binutil.go | 4 +++- lib/binstruct/unmarshal.go | 3 +++ lib/btrfs/btrfsitem/items.go | 2 ++ lib/btrfs/btrfsprim/misc.go | 2 ++ lib/btrfs/btrfssum/csum.go | 2 ++ lib/btrfs/btrfstree/btree.go | 2 ++ lib/btrfs/btrfsvol/lvm.go | 2 ++ lib/btrfs/io1_pv.go | 2 ++ lib/btrfscheck/graph.go | 2 ++ lib/btrfsutil/doc.go | 7 +++++++ lib/containers/doc.go | 7 +++++++ lib/diskio/file_iface.go | 3 ++- lib/fmtutil/fmt.go | 4 +++- lib/maps/maputil.go | 4 +++- lib/profile/profile.go | 2 ++ lib/slices/sliceutil.go | 4 +++- lib/streamio/runescanner.go | 2 ++ lib/textui/text.go | 2 ++ 23 files changed, 63 insertions(+), 6 deletions(-) create mode 100644 lib/btrfsutil/doc.go create mode 100644 lib/containers/doc.go 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 +// Copyright (C) 2022-2023 Luke Shumaker // // 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 +// +// 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 +// +// 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 +// Copyright (C) 2022-2023 Luke Shumaker // // 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 +// Copyright (C) 2022-2023 Luke Shumaker // // 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 +// Copyright (C) 2022-2023 Luke Shumaker // // 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 +// Copyright (C) 2022-2023 Luke Shumaker // // 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 ( -- cgit v1.2.3-2-g168b