From 5048af3a8ff6488733c8458ec17a1d1edd5420fe Mon Sep 17 00:00:00 2001
From: Charles Hall <charles@computer.surgery>
Date: Tue, 21 May 2024 22:05:41 -0700
Subject: [PATCH] enable `doc_markdown` lint

---
 Cargo.toml           |  1 -
 src/database.rs      |  9 +++++----
 src/service/admin.rs | 12 +++++++++++-
 src/utils/error.rs   |  2 +-
 4 files changed, 17 insertions(+), 7 deletions(-)

diff --git a/Cargo.toml b/Cargo.toml
index cb75b2f3..fbe0d34f 100644
--- a/Cargo.toml
+++ b/Cargo.toml
@@ -72,7 +72,6 @@ wildcard_dependencies = "warn"
 missing_errors_doc = "allow"
 missing_panics_doc = "allow"
 
-doc_markdown = "allow"
 manual_is_variant_and = "allow"
 mixed_attributes_style = "allow"
 multiple_bound_locations = "allow"
diff --git a/src/database.rs b/src/database.rs
index 72d2e3c5..44d7b1c4 100644
--- a/src/database.rs
+++ b/src/database.rs
@@ -159,7 +159,7 @@ pub(crate) struct KeyValueDatabase {
     /// Remember the state hash at events in the past.
     pub(super) shorteventid_shortstatehash: Arc<dyn KvTree>,
 
-    /// StateKey = EventType + StateKey, ShortStateKey = Count
+    /// `StateKey = EventType + StateKey`, `ShortStateKey = Count`
     pub(super) statekey_shortstatekey: Arc<dyn KvTree>,
     pub(super) shortstatekey_statekey: Arc<dyn KvTree>,
 
@@ -176,16 +176,17 @@ pub(crate) struct KeyValueDatabase {
 
     pub(super) shorteventid_authchain: Arc<dyn KvTree>,
 
-    /// RoomId + EventId -> outlier PDU.
+    /// `RoomId + EventId -> outlier PDU`
+    ///
     /// Any pdu that has passed the steps 1-8 in the incoming event
     /// /federation/send/txn.
     pub(super) eventid_outlierpdu: Arc<dyn KvTree>,
     pub(super) softfailedeventids: Arc<dyn KvTree>,
 
-    /// ShortEventId + ShortEventId -> ().
+    /// `ShortEventId + ShortEventId -> ()`
     pub(super) tofrom_relation: Arc<dyn KvTree>,
 
-    /// RoomId + EventId -> Parent PDU EventId.
+    /// `RoomId + EventId -> Parent PDU EventId`
     pub(super) referencedevents: Arc<dyn KvTree>,
 
     // Trees "owned" by `self::key_value::account_data`
diff --git a/src/service/admin.rs b/src/service/admin.rs
index bd14e045..00f30e75 100644
--- a/src/service/admin.rs
+++ b/src/service/admin.rs
@@ -60,6 +60,8 @@ enum AdminCommand {
     /// # ```
     /// # yaml content here
     /// # ```
+    // Allowed because the doc comment gets parsed by our code later
+    #[allow(clippy::doc_markdown)]
     RegisterAppservice,
 
     /// Unregister an appservice using its ID
@@ -107,6 +109,8 @@ enum AdminCommand {
     /// # ```
     /// # User list here
     /// # ```
+    // Allowed because the doc comment gets parsed by our code later
+    #[allow(clippy::doc_markdown)]
     DeactivateAll {
         #[arg(short, long)]
         /// Remove users from their joined rooms
@@ -116,7 +120,7 @@ enum AdminCommand {
         force: bool,
     },
 
-    /// Get the auth_chain of a PDU
+    /// Get the `auth_chain` of a PDU
     GetAuthChain {
         /// An event ID (the $ character followed by the base64 reference hash)
         event_id: Box<EventId>,
@@ -132,6 +136,8 @@ enum AdminCommand {
     /// # ```
     /// # PDU json content here
     /// # ```
+    // Allowed because the doc comment gets parsed by our code later
+    #[allow(clippy::doc_markdown)]
     ParsePdu,
 
     /// Retrieve and print a PDU by ID from the Grapevine database
@@ -186,6 +192,8 @@ enum AdminCommand {
     /// # ```
     /// # json here
     /// # ```
+    // Allowed because the doc comment gets parsed by our code later
+    #[allow(clippy::doc_markdown)]
     SignJson,
 
     /// Verify json signatures
@@ -193,6 +201,8 @@ enum AdminCommand {
     /// # ```
     /// # json here
     /// # ```
+    // Allowed because the doc comment gets parsed by our code later
+    #[allow(clippy::doc_markdown)]
     VerifyJson,
 }
 
diff --git a/src/utils/error.rs b/src/utils/error.rs
index 793a2890..3491d85c 100644
--- a/src/utils/error.rs
+++ b/src/utils/error.rs
@@ -63,7 +63,7 @@ pub(crate) enum Error {
     #[error("{0}")]
     BadConfig(&'static str),
     #[error("{0}")]
-    /// Don't create this directly. Use Error::bad_database instead.
+    /// Don't create this directly. Use [`Error::bad_database`] instead.
     BadDatabase(&'static str),
     #[error("uiaa")]
     Uiaa(UiaaInfo),