cli/docs: Expand and clean up clap doctext a bit

cgwalters · cgwalters · commit 1f0ef587cb58 · 2024-06-17T11:33:29.000-04:00
It seems like in clap one can document both the verb and the option
structure. Change things to consistently document the verbs, and
expand the text.

Signed-off-by: Colin Walters &lt;walters@verbum.org&gt;
diff --git a/docs/src/man/bootc-container-lint.md b/docs/src/man/bootc-container-lint.md
@@ -10,13 +10,16 @@ checks as part of a container build
 # DESCRIPTION
 
 Perform relatively inexpensive static analysis checks as part of a
-container build
+container build.
+
+This is intended to be invoked via e.g. \`RUN bootc container lint\` as
+part of a build process; it will error if any problems are detected.
 
 # OPTIONS
 
 **-h**, **\--help**
 
-:   Print help
+:   Print help (see a summary with -h)
 
 # VERSION
 
diff --git a/docs/src/man/bootc-install-to-disk.md b/docs/src/man/bootc-install-to-disk.md
@@ -14,7 +14,16 @@ bootc-install-to-disk - Install to the target block device
 
 # DESCRIPTION
 
-Install to the target block device
+Install to the target block device.
+
+This command must be invoked inside of the container, which will be
+installed. The container must be run in \`\--privileged\` mode, and
+hence will be able to see all block devices on the system.
+
+The default storage layout uses the root filesystem type configured in
+the container image, alongside any required system partitions such as
+the EFI system partition. Use \`install to-filesystem\` for anything
+more complex such as RAID, LVM, LUKS etc.
 
 # OPTIONS
 
@@ -58,7 +67,8 @@ previous paragraph. See skopeo(1) for accepted formats.
 
 **\--target-transport**=*TARGET_TRANSPORT* \[default: registry\]
 
-:   The transport; e.g. oci, oci-archive, containers-storage. Defaults to \`registry\`
+:   The transport; e.g. oci, oci-archive, containers-storage. Defaults
+    to \`registry\`
 
 **\--target-imgref**=*TARGET_IMGREF*
 
diff --git a/docs/src/man/bootc-install-to-existing-root.md b/docs/src/man/bootc-install-to-existing-root.md
@@ -1,7 +1,6 @@
 # NAME
 
-bootc-install-to-existing-root - Perform an installation to the host
-root filesystem
+bootc-install-to-existing-root - Install to the host root filesystem
 
 # SYNOPSIS
 
@@ -16,7 +15,13 @@ root filesystem
 
 # DESCRIPTION
 
-Perform an installation to the host root filesystem
+Install to the host root filesystem.
+
+This is a variant of \`install to-filesystem\` that is designed to
+install \"alongside\" the running host root filesystem. Currently, the
+host root filesystems \`/boot\` partition will be wiped, but the content
+of the existing root will otherwise be retained, and will need to be
+cleaned up if desired when rebooted into the new root.
 
 # OPTIONS
 
@@ -48,7 +53,8 @@ previous paragraph. See skopeo(1) for accepted formats.
 
 **\--target-transport**=*TARGET_TRANSPORT* \[default: registry\]
 
-:   The transport; e.g. oci, oci-archive, containers-storage. Defaults to \`registry\`
+:   The transport; e.g. oci, oci-archive, containers-storage. Defaults
+    to \`registry\`
 
 **\--target-imgref**=*TARGET_IMGREF*
 
diff --git a/docs/src/man/bootc-install-to-filesystem.md b/docs/src/man/bootc-install-to-filesystem.md
@@ -1,6 +1,7 @@
 # NAME
 
-bootc-install-to-filesystem - Install to the target filesystem
+bootc-install-to-filesystem - Install to an externally created
+filesystem structure
 
 # SYNOPSIS
 
@@ -16,7 +17,12 @@ bootc-install-to-filesystem - Install to the target filesystem
 
 # DESCRIPTION
 
-Install to the target filesystem
+Install to an externally created filesystem structure.
+
+In this variant of installation, the root filesystem alongside any
+necessary platform partitions (such as the EFI system partition) are
+prepared and mounted by an external tool or script. The root filesystem
+is currently expected to be empty by default.
 
 # OPTIONS
 
@@ -75,7 +81,8 @@ previous paragraph. See skopeo(1) for accepted formats.
 
 **\--target-transport**=*TARGET_TRANSPORT* \[default: registry\]
 
-:   The transport; e.g. oci, oci-archive, containers-storage. Defaults to \`registry\`
+:   The transport; e.g. oci, oci-archive, containers-storage. Defaults
+    to \`registry\`
 
 **\--target-imgref**=*TARGET_IMGREF*
 
diff --git a/docs/src/man/bootc-install.md b/docs/src/man/bootc-install.md
@@ -42,11 +42,11 @@ bootc-install-to-disk(8)
 
 bootc-install-to-filesystem(8)
 
-:   Install to the target filesystem
+:   Install to an externally created filesystem structure
 
 bootc-install-to-existing-root(8)
 
-:   Perform an installation to the host root filesystem
+:   Install to the host root filesystem
 
 bootc-install-print-configuration(8)
 
diff --git a/docs/src/man/bootc-switch.md b/docs/src/man/bootc-switch.md
@@ -32,7 +32,8 @@ updates via container image tags; for example,
 
 **\--transport**=*TRANSPORT* \[default: registry\]
 
-:   The transport; e.g. oci, oci-archive, containers-storage. Defaults to \`registry\`
+:   The transport; e.g. oci, oci-archive, containers-storage. Defaults
+    to \`registry\`
 
 **\--enforce-container-sigpolicy**
 
diff --git a/lib/src/cli.rs b/lib/src/cli.rs
@@ -118,18 +118,37 @@ pub(crate) struct StatusOpts {
     pub(crate) booted: bool,
 }
 
-/// Options for internal testing
 #[cfg(feature = "install")]
 #[derive(Debug, clap::Subcommand, PartialEq, Eq)]
 pub(crate) enum InstallOpts {
-    /// Install to the target block device
+    /// Install to the target block device.
+    ///
+    /// This command must be invoked inside of the container, which will be
+    /// installed. The container must be run in `--privileged` mode, and hence
+    /// will be able to see all block devices on the system.
+    ///
+    /// The default storage layout uses the root filesystem type configured
+    /// in the container image, alongside any required system partitions such as
+    /// the EFI system partition. Use `install to-filesystem` for anything more
+    /// complex such as RAID, LVM, LUKS etc.
     ToDisk(crate::install::InstallToDiskOpts),
-    /// Install to the target filesystem
+    /// Install to an externally created filesystem structure.
+    ///
+    /// In this variant of installation, the root filesystem alongside any necessary
+    /// platform partitions (such as the EFI system partition) are prepared and mounted by an
+    /// external tool or script. The root filesystem is currently expected to be empty
+    /// by default.
     ToFilesystem(crate::install::InstallToFilesystemOpts),
+    /// Install to the host root filesystem.
+    ///
+    /// This is a variant of `install to-filesystem` that is designed to install "alongside"
+    /// the running host root filesystem. Currently, the host root filesystem's `/boot` partition
+    /// will be wiped, but the content of the existing root will otherwise be retained, and will
+    /// need to be cleaned up if desired when rebooted into the new root.
     ToExistingRoot(crate::install::InstallToExistingRootOpts),
     /// Output JSON to stdout that contains the merged installation configuration
     /// as it may be relevant to calling processes using `install to-filesystem`
-    /// that want to honor e.g. `root-fs-type`.
+    /// that in particular want to discover the desired root filesystem type from the container image.
     ///
     /// At the current time, the only output key is `root-fs-type` which is a string-valued
     /// filesystem name suitable for passing to `mkfs.$type`.
@@ -149,6 +168,9 @@ pub(crate) struct ManOpts {
 pub(crate) enum ContainerOpts {
     /// Perform relatively inexpensive static analysis checks as part of a container
     /// build.
+    ///
+    /// This is intended to be invoked via e.g. `RUN bootc container lint` as part
+    /// of a build process; it will error if any problems are detected.
     Lint,
 }
 
diff --git a/lib/src/install.rs b/lib/src/install.rs
@@ -161,7 +161,6 @@ pub(crate) struct InstallConfigOpts {
     pub(crate) generic_image: bool,
 }
 
-/// Perform an installation to a block device.
 #[derive(Debug, Clone, clap::Parser, Serialize, Deserialize, PartialEq, Eq)]
 pub(crate) struct InstallToDiskOpts {
     #[clap(flatten)]
@@ -244,7 +243,6 @@ pub(crate) struct InstallTargetFilesystemOpts {
     pub(crate) skip_finalize: bool,
 }
 
-/// Perform an installation to a mounted filesystem.
 #[derive(Debug, Clone, clap::Parser, PartialEq, Eq)]
 pub(crate) struct InstallToFilesystemOpts {
     #[clap(flatten)]
@@ -260,7 +258,6 @@ pub(crate) struct InstallToFilesystemOpts {
     pub(crate) config_opts: InstallConfigOpts,
 }
 
-/// Perform an installation to the host root filesystem.
 #[derive(Debug, Clone, clap::Parser, PartialEq, Eq)]
 pub(crate) struct InstallToExistingRootOpts {
     /// Configure how existing data is treated.

Original file line number	Diff line number	Diff line change
`@@ -161,7 +161,6 @@ pub(crate) struct InstallConfigOpts {`
`161`	`161`	`pub(crate) generic_image: bool,`
`162`	`162`	`}`
`163`	`163`
`164`		`-/// Perform an installation to a block device.`
`165`	`164`	`#[derive(Debug, Clone, clap::Parser, Serialize, Deserialize, PartialEq, Eq)]`
`166`	`165`	`pub(crate) struct InstallToDiskOpts {`
`167`	`166`	`#[clap(flatten)]`
`@@ -244,7 +243,6 @@ pub(crate) struct InstallTargetFilesystemOpts {`
`244`	`243`	`pub(crate) skip_finalize: bool,`
`245`	`244`	`}`
`246`	`245`
`247`		`-/// Perform an installation to a mounted filesystem.`
`248`	`246`	`#[derive(Debug, Clone, clap::Parser, PartialEq, Eq)]`
`249`	`247`	`pub(crate) struct InstallToFilesystemOpts {`
`250`	`248`	`#[clap(flatten)]`
`@@ -260,7 +258,6 @@ pub(crate) struct InstallToFilesystemOpts {`
`260`	`258`	`pub(crate) config_opts: InstallConfigOpts,`
`261`	`259`	`}`
`262`	`260`
`263`		`-/// Perform an installation to the host root filesystem.`
`264`	`261`	`#[derive(Debug, Clone, clap::Parser, PartialEq, Eq)]`
`265`	`262`	`pub(crate) struct InstallToExistingRootOpts {`
`266`	`263`	`/// Configure how existing data is treated.`