From cc3ef1a8be08b9212a16957062304d7bd5da1111 Mon Sep 17 00:00:00 2001
From: Andrei Vasiliu <whyte.vuhuni@gmail.com>
Date: Fri, 21 Jan 2022 11:06:16 +0200
Subject: [PATCH] Improve help text for admin commands

---
 src/database/admin.rs | 27 ++++++++++++++++++++++-----
 1 file changed, 22 insertions(+), 5 deletions(-)

diff --git a/src/database/admin.rs b/src/database/admin.rs
index f690bdf4..362ef294 100644
--- a/src/database/admin.rs
+++ b/src/database/admin.rs
@@ -147,6 +147,7 @@ impl Admin {
     }
 }
 
+// Parse chat messages from the admin room into an AdminCommand object
 pub fn parse_admin_command(db: &Database, command_line: &str, body: Vec<&str>) -> AdminCommand {
     let mut argv: Vec<_> = command_line.split_whitespace().skip(1).collect();
 
@@ -191,10 +192,13 @@ pub fn parse_admin_command(db: &Database, command_line: &str, body: Vec<&str>) -
 #[derive(StructOpt)]
 enum AdminCommands {
     #[structopt(verbatim_doc_comment)]
-    /// Register a bridge using its registration YAML
+    /// Register an appservice using its registration YAML
     ///
-    /// This command needs a YAML generated by an appservice (such as a mautrix
-    /// bridge), which must be provided in a code-block below the command.
+    /// This command needs a YAML generated by an appservice (such as a bridge),
+    /// which must be provided in a Markdown code-block below the command.
+    ///
+    /// Registering a new bridge using the ID of an existing bridge will replace
+    /// the old one.
     ///
     /// Example:
     /// ````
@@ -204,16 +208,27 @@ enum AdminCommands {
     /// ```
     /// ````
     RegisterAppservice,
-    /// Unregister a bridge using its ID
+
+    /// Unregister an appservice using its ID
+    /// 
+    /// You can find the ID using the `list-appservices` command.
     UnregisterAppservice { appservice_identifier: String },
-    /// List all the currently registered bridges
+
+    /// List all the currently registered appservices
     ListAppservices,
+
     /// Get the auth_chain of a PDU
     GetAuthChain { event_id: Box<EventId> },
+
     /// Parse and print a PDU from a JSON
+    ///
+    /// The PDU event is only checked for validity and is not added to the
+    /// database.
     ParsePdu,
+
     /// Retrieve and print a PDU by ID from the Conduit database
     GetPdu { event_id: Box<EventId> },
+
     /// Print database memory usage statistics
     DatabaseMemoryUsage,
 }
@@ -365,6 +380,7 @@ pub fn try_parse_admin_command(
     Ok(admin_command)
 }
 
+// Utility to turn structopt's `--help` text to markdown.
 fn usage_to_markdown(text: &str) -> String {
     // For the conduit admin room, subcommands become main commands
     let text = text.replace("SUBCOMMAND", "COMMAND");
@@ -390,6 +406,7 @@ fn usage_to_markdown(text: &str) -> String {
     text.to_string()
 }
 
+// Convert markdown to HTML using the CommonMark flavor
 fn markdown_to_html(text: &str) -> String {
     // CommonMark's spec allows HTML tags; however, CLI required arguments look
     // very much like tags so escape them.