From 5ba74d78720502bf0ff67464f9a3e81be70b8dc3 Mon Sep 17 00:00:00 2001
From: ryan <ryan@distrust.co>
Date: Thu, 11 Jan 2024 21:50:16 -0500
Subject: [PATCH] keyfork: tidy up some docs

---
 keyfork/src/cli/derive.rs  | 5 +++--
 keyfork/src/cli/mod.rs     | 9 +++++----
 keyfork/src/cli/recover.rs | 3 ++-
 3 files changed, 10 insertions(+), 7 deletions(-)

diff --git a/keyfork/src/cli/derive.rs b/keyfork/src/cli/derive.rs
index 9da9aa3..1e247f9 100644
--- a/keyfork/src/cli/derive.rs
+++ b/keyfork/src/cli/derive.rs
@@ -17,10 +17,11 @@ type Result<T, E = Box<dyn std::error::Error>> = std::result::Result<T, E>;
 
 #[derive(Subcommand, Clone, Debug)]
 pub enum DeriveSubcommands {
-    /// Derive an OpenPGP certificate.
+    /// Derive an OpenPGP Transferable Secret Key (private key). The key is encoded using OpenPGP
+    /// ASCII Armor, a format usable by most programs using OpenPGP.
     #[command(name = "openpgp")]
     OpenPGP {
-        /// Default User ID for the certificate.
+        /// Default User ID for the certificate, using the OpenPGP User ID format.
         user_id: String,
     },
 }
diff --git a/keyfork/src/cli/mod.rs b/keyfork/src/cli/mod.rs
index 5bd4b1d..5f3b16c 100644
--- a/keyfork/src/cli/mod.rs
+++ b/keyfork/src/cli/mod.rs
@@ -18,20 +18,21 @@ pub struct Keyfork {
 
 #[derive(Subcommand, Clone, Debug)]
 pub enum KeyforkCommands {
-    /// Derive keys of various formats.
+    /// Derive keys of various formats. These commands require that the Keyfork server is running,
+    /// which can be started by running a `keyfork recover` command.
     Derive(derive::Derive),
 
     /// Mnemonic generation and persistence utilities.
     Mnemonic(mnemonic::Mnemonic),
 
-    /// Splitting and combining secrets using Shamir's Secret Sharing.
+    /// Splitting and combining secrets, using Shamir's Secret Sharing.
     Shard(shard::Shard),
 
-    /// Derive and deploy keys.
+    /// Derive and deploy keys to hardware.
     #[command(subcommand_negates_reqs(true))]
     Provision(provision::Provision),
 
-    /// Recover a seed using a recovery mechanism and begin the Keyfork daemon.
+    /// Recover a seed using the requested recovery mechanism and start the Keyfork server.
     Recover(recover::Recover),
 
     /// Utilities to automatically manage the setup of Keyfork.
diff --git a/keyfork/src/cli/recover.rs b/keyfork/src/cli/recover.rs
index 0c7e8ea..d25960b 100644
--- a/keyfork/src/cli/recover.rs
+++ b/keyfork/src/cli/recover.rs
@@ -18,7 +18,8 @@ pub enum RecoverSubcommands {
         key_discovery: Option<PathBuf>,
     },
 
-    /// Combine remotely decrypted shards.
+    /// Combine remotely decrypted shards. The shards should be sent using the command `keyfork
+    /// shard transport`.
     RemoteShard {},
 }