From 311c7d83caa6d61226dbb99cb8c9d8225377548c Mon Sep 17 00:00:00 2001
From: Charles Hall <charles@computer.surgery>
Date: Wed, 20 Dec 2023 16:27:40 -0800
Subject: [PATCH] fix rustdoc warnings

Also removed all instances of `#[command(verbatim_doc_comment)]` because
I'm pretty sure it's not necessary anymore. The `[commandbody]` things
were making rustdoc upset about broken link syntax. I also normalized
"code-block" to "code block" in that file since the latter appears more
often.
---
 src/api/server_server.rs |  2 +-
 src/service/admin/mod.rs | 40 +++++++++++-----------------------------
 2 files changed, 12 insertions(+), 30 deletions(-)

diff --git a/src/api/server_server.rs b/src/api/server_server.rs
index 017179b2..ee71c2b1 100644
--- a/src/api/server_server.rs
+++ b/src/api/server_server.rs
@@ -365,7 +365,7 @@ fn add_port_to_hostname(destination_str: &str) -> FedDest {
 }
 
 /// Returns: actual_destination, host header
-/// Implemented according to the specification at https://matrix.org/docs/spec/server_server/r0.1.4#resolving-server-names
+/// Implemented according to the specification at <https://matrix.org/docs/spec/server_server/r0.1.4#resolving-server-names>
 /// Numbers in comments below refer to bullet points in linked section of specification
 async fn find_actual_destination(destination: &'_ ServerName) -> (FedDest, FedDest) {
     debug!("Finding actual destination for {destination}");
diff --git a/src/service/admin/mod.rs b/src/service/admin/mod.rs
index c4960e27..fb905fd1 100644
--- a/src/service/admin/mod.rs
+++ b/src/service/admin/mod.rs
@@ -77,22 +77,15 @@ enum AdminCommand {
 #[cfg_attr(test, derive(Debug))]
 #[derive(Subcommand)]
 enum AppserviceCommand {
-    #[command(verbatim_doc_comment)]
     /// Register an appservice using its registration YAML
     ///
     /// 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.
+    /// 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.
-    ///
-    /// [commandbody]
-    /// # ```
-    /// # yaml content here
-    /// # ```
     Register,
 
-    #[command(verbatim_doc_comment)]
     /// Unregister an appservice using its ID
     ///
     /// You can find the ID using the `list-appservices` command.
@@ -101,7 +94,6 @@ enum AppserviceCommand {
         appservice_identifier: String,
     },
 
-    #[command(verbatim_doc_comment)]
     /// Show an appservice's config using its ID
     ///
     /// You can find the ID using the `list-appservices` command.
@@ -141,7 +133,6 @@ enum UserCommand {
         user_id: Box<UserId>,
     },
 
-    #[command(verbatim_doc_comment)]
     /// Deactivate a list of users
     ///
     /// Recommended to use in conjunction with list-local-users.
@@ -151,10 +142,8 @@ enum UserCommand {
     /// Removing a mass amount of users from a room may cause a significant amount of leave events.
     /// The time to leave rooms may depend significantly on joined rooms and servers.
     ///
-    /// [commandbody]
-    /// # ```
-    /// # User list here
-    /// # ```
+    /// This command needs a newline separated list of users provided in a
+    /// Markdown code block below the command.
     DeactivateAll {
         #[arg(short, long)]
         /// Remove users from their joined rooms
@@ -249,20 +238,16 @@ enum FederationCommand {
     /// Enables incoming federation handling for a room again.
     EnableRoom { room_id: Box<RoomId> },
 
-    #[command(verbatim_doc_comment)]
     /// Verify json signatures
-    /// [commandbody]
-    /// # ```
-    /// # json here
-    /// # ```
+    ///
+    /// This command needs a JSON blob provided in a Markdown code block below
+    /// the command.
     SignJson,
 
-    #[command(verbatim_doc_comment)]
     /// Verify json signatures
-    /// [commandbody]
-    /// # ```
-    /// # json here
-    /// # ```
+    ///
+    /// This command needs a JSON blob provided in a Markdown code block below
+    /// the command.
     VerifyJson,
 }
 
@@ -275,16 +260,13 @@ enum DebugCommand {
         event_id: Box<EventId>,
     },
 
-    #[command(verbatim_doc_comment)]
     /// Parse and print a PDU from a JSON
     ///
     /// The PDU event is only checked for validity and is not added to the
     /// database.
     ///
-    /// [commandbody]
-    /// # ```
-    /// # PDU json content here
-    /// # ```
+    /// This command needs a JSON blob provided in a Markdown code block below
+    /// the command.
     ParsePdu,
 
     /// Retrieve and print a PDU by ID from the Conduit database