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.