From da440934bda39f0609e3accfd0b728a53555f520 Mon Sep 17 00:00:00 2001 From: Charles Hall Date: Tue, 14 May 2024 16:34:10 -0700 Subject: [PATCH] enable `doc_markdown` lint --- Cargo.toml | 1 + clippy.toml | 4 ++++ src/api/client_server/account.rs | 10 +++++----- src/api/client_server/context.rs | 2 +- src/api/client_server/message.rs | 2 +- src/api/client_server/profile.rs | 8 ++++---- src/api/client_server/room.rs | 4 ++-- src/api/client_server/space.rs | 2 +- src/api/client_server/state.rs | 4 ++-- src/api/client_server/sync.rs | 6 +++--- src/api/server_server.rs | 6 +++--- src/database/key_value/rooms/short.rs | 2 +- src/database/key_value/users.rs | 14 +++++++------- src/service/media/data.rs | 2 +- src/service/rooms/edus/read_receipt/data.rs | 2 +- src/service/rooms/edus/typing.rs | 2 +- src/service/rooms/short.rs | 2 +- src/service/rooms/short/data.rs | 2 +- src/service/rooms/state/data.rs | 4 ++-- src/service/users.rs | 8 ++++---- src/service/users/data.rs | 10 +++++----- 21 files changed, 51 insertions(+), 46 deletions(-) create mode 100644 clippy.toml diff --git a/Cargo.toml b/Cargo.toml index 02c1cfe2..f7cb3022 100644 --- a/Cargo.toml +++ b/Cargo.toml @@ -24,6 +24,7 @@ dbg_macro = "warn" default_trait_access = "warn" default_union_representation = "warn" deref_by_slicing = "warn" +doc_markdown = "warn" empty_drop = "warn" empty_structs_with_brackets = "warn" error_impl_error = "warn" diff --git a/clippy.toml b/clippy.toml new file mode 100644 index 00000000..a6330574 --- /dev/null +++ b/clippy.toml @@ -0,0 +1,4 @@ +doc-valid-idents = [ + "SemVer", + "..", +] diff --git a/src/api/client_server/account.rs b/src/api/client_server/account.rs index 784a00bb..e10d83a5 100644 --- a/src/api/client_server/account.rs +++ b/src/api/client_server/account.rs @@ -69,11 +69,11 @@ pub(crate) async fn get_register_available_route( /// to check if the user id is valid and available. /// /// - Only works if registration is enabled -/// - If type is guest: ignores all parameters except initial_device_display_name +/// - If type is guest: ignores all parameters except `initial_device_display_name` /// - If sender is not appservice: Requires UIAA (but we only use a dummy stage) /// - If type is not guest and no username is given: Always fails after UIAA check /// - Creates a new account and populates it with default account data -/// - If `inhibit_login` is false: Creates a device and returns device id and access_token +/// - If `inhibit_login` is false: Creates a device and returns `device_id` and `access_token` pub(crate) async fn register_route( body: Ruma, ) -> Result { @@ -304,9 +304,9 @@ pub(crate) async fn register_route( /// - The password hash is calculated using argon2 with 32 character salt, the plain password is /// not saved /// -/// If logout_devices is true it does the following for each device except the sender device: +/// If `logout_devices` is true it does the following for each device except the sender device: /// - Invalidates access token -/// - Deletes device metadata (device id, device display name, last seen ip, last seen ts) +/// - Deletes device metadata (device ID, device display name, last seen IP, last seen timestamp) /// - Forgets to-device events /// - Triggers device list updates pub(crate) async fn change_password_route( @@ -372,7 +372,7 @@ pub(crate) async fn change_password_route( /// # `GET _matrix/client/r0/account/whoami` /// -/// Get user_id of the sender user. +/// Get `user_id` of the sender user. /// /// Note: Also works for Application Services pub(crate) async fn whoami_route(body: Ruma) -> Result { diff --git a/src/api/client_server/context.rs b/src/api/client_server/context.rs index db83fc8f..a91f536a 100644 --- a/src/api/client_server/context.rs +++ b/src/api/client_server/context.rs @@ -12,7 +12,7 @@ use tracing::error; /// Allows loading room history around an event. /// /// - Only works if the user is joined (TODO: always allow, but only show events if the user was -/// joined, depending on history_visibility) +/// joined, depending on `history_visibility`) pub(crate) async fn get_context_route( body: Ruma, ) -> Result { diff --git a/src/api/client_server/message.rs b/src/api/client_server/message.rs index 1d86cf2b..dec75e7a 100644 --- a/src/api/client_server/message.rs +++ b/src/api/client_server/message.rs @@ -111,7 +111,7 @@ pub(crate) async fn send_message_event_route( /// Allows paginating through room history. /// /// - Only works if the user is joined (TODO: always allow, but only show events where the user was -/// joined, depending on history_visibility) +/// joined, depending on `history_visibility`) pub(crate) async fn get_message_events_route( body: Ruma, ) -> Result { diff --git a/src/api/client_server/profile.rs b/src/api/client_server/profile.rs index 3a86d81d..3e9806cd 100644 --- a/src/api/client_server/profile.rs +++ b/src/api/client_server/profile.rs @@ -130,7 +130,7 @@ pub(crate) async fn get_displayname_route( /// # `PUT /_matrix/client/r0/profile/{userId}/avatar_url` /// -/// Updates the avatar_url and blurhash. +/// Updates the `avatar_url` and `blurhash`. /// /// - Also makes sure other users receive the update using presence EDUs pub(crate) async fn set_avatar_url_route( @@ -217,9 +217,9 @@ pub(crate) async fn set_avatar_url_route( /// # `GET /_matrix/client/r0/profile/{userId}/avatar_url` /// -/// Returns the avatar_url and blurhash of the user. +/// Returns the `avatar_url` and `blurhash` of the user. /// -/// - If user is on another server: Fetches avatar_url and blurhash over federation +/// - If user is on another server: Fetches `avatar_url` and `blurhash` over federation pub(crate) async fn get_avatar_url_route( body: Ruma, ) -> Result { @@ -249,7 +249,7 @@ pub(crate) async fn get_avatar_url_route( /// # `GET /_matrix/client/r0/profile/{userId}` /// -/// Returns the displayname, avatar_url and blurhash of the user. +/// Returns the `displayname`, `avatar_url` and `blurhash` of the user. /// /// - If user is on another server: Fetches profile over federation pub(crate) async fn get_profile_route( diff --git a/src/api/client_server/room.rs b/src/api/client_server/room.rs index f3edf62d..420e7110 100644 --- a/src/api/client_server/room.rs +++ b/src/api/client_server/room.rs @@ -34,7 +34,7 @@ use tracing::{info, warn}; /// Creates a new room. /// /// - Room ID is randomly generated -/// - Create alias if room_alias_name is set +/// - Create alias if `room_alias_name` is set /// - Send create event /// - Join sender user /// - Send power levels event @@ -543,7 +543,7 @@ pub(crate) async fn get_room_event_route( /// /// Lists all aliases of the room. /// -/// - Only users joined to the room are allowed to call this TODO: Allow any user to call it if history_visibility is world readable +/// - Only users joined to the room are allowed to call this TODO: Allow any user to call it if `history_visibility` is world readable pub(crate) async fn get_room_aliases_route( body: Ruma, ) -> Result { diff --git a/src/api/client_server/space.rs b/src/api/client_server/space.rs index a05d5c36..43463184 100644 --- a/src/api/client_server/space.rs +++ b/src/api/client_server/space.rs @@ -1,7 +1,7 @@ use crate::{services, Result, Ruma}; use ruma::{api::client::space::get_hierarchy, uint}; -/// # `GET /_matrix/client/v1/rooms/{room_id}/hierarchy`` +/// # `GET /_matrix/client/v1/rooms/{room_id}/hierarchy` /// /// Paginates over the space tree in a depth-first manner to locate child rooms of a given space. pub(crate) async fn get_hierarchy_route( diff --git a/src/api/client_server/state.rs b/src/api/client_server/state.rs index 97d9821e..35d78dc3 100644 --- a/src/api/client_server/state.rs +++ b/src/api/client_server/state.rs @@ -20,7 +20,7 @@ use tracing::log::warn; /// /// - The only requirement for the content is that it has to be valid json /// - Tries to send the event into the room, auth rules will determine if it is allowed -/// - If event is new canonical_alias: Rejects if alias is incorrect +/// - If event is new `canonical_alias`: Rejects if alias is incorrect pub(crate) async fn send_state_event_for_key_route( body: Ruma, ) -> Result { @@ -45,7 +45,7 @@ pub(crate) async fn send_state_event_for_key_route( /// /// - The only requirement for the content is that it has to be valid json /// - Tries to send the event into the room, auth rules will determine if it is allowed -/// - If event is new canonical_alias: Rejects if alias is incorrect +/// - If event is new `canonical_alias`: Rejects if alias is incorrect pub(crate) async fn send_state_event_for_empty_key_route( body: Ruma, ) -> Result> { diff --git a/src/api/client_server/sync.rs b/src/api/client_server/sync.rs index a7167d26..4004bc42 100644 --- a/src/api/client_server/sync.rs +++ b/src/api/client_server/sync.rs @@ -46,8 +46,8 @@ use tracing::{debug, error, info}; /// /// Calling this endpoint with a `since` parameter from a previous `next_batch` returns: /// For joined rooms: -/// - Some of the most recent events of each timeline that happened after since -/// - If user joined the room after since: All state events (unless lazy loading is activated) and +/// - Some of the most recent events of each timeline that happened after `since` +/// - If user joined the room after `since`: All state events (unless lazy loading is activated) and /// all device list updates in that room /// - If the user was already in the room: A list of all events that are in the state now, but were /// not in the state at `since` @@ -61,7 +61,7 @@ use tracing::{debug, error, info}; /// - If the user was invited after `since`: A subset of the state of the room at the point of the invite /// /// For left rooms: -/// - If the user left after `since`: prev_batch token, empty state (TODO: subset of the state at the point of the leave) +/// - If the user left after `since`: `prev_batch` token, empty state (TODO: subset of the state at the point of the leave) /// /// - Sync is handled in an async task, multiple requests from the same device with the same /// `since` will be cached diff --git a/src/api/server_server.rs b/src/api/server_server.rs index eae0ed7a..781ee74c 100644 --- a/src/api/server_server.rs +++ b/src/api/server_server.rs @@ -61,8 +61,8 @@ use tracing::{debug, error, warn}; /// Wraps either an literal IP address plus port, or a hostname plus complement /// (colon-plus-port if it was specified). /// -/// Note: A `FedDest::Named` might contain an IP address in string form if there -/// was no port specified to construct a SocketAddr with. +/// Note: A [`FedDest::Named`] might contain an IP address in string form if there +/// was no port specified to construct a [`SocketAddr`] with. /// /// # Examples: /// ```rust @@ -340,7 +340,7 @@ fn add_port_to_hostname(destination_str: &str) -> FedDest { FedDest::Named(host.to_owned(), port.to_owned()) } -/// Returns: actual_destination, host header +/// Returns: `actual_destination`, `Host` header /// Implemented according to the specification at /// Numbers in comments below refer to bullet points in linked section of specification async fn find_actual_destination(destination: &'_ ServerName) -> (FedDest, FedDest) { diff --git a/src/database/key_value/rooms/short.rs b/src/database/key_value/rooms/short.rs index 98cfa48a..6ec4dd5f 100644 --- a/src/database/key_value/rooms/short.rs +++ b/src/database/key_value/rooms/short.rs @@ -175,7 +175,7 @@ impl service::rooms::short::Data for KeyValueDatabase { Ok(result) } - /// Returns (shortstatehash, already_existed) + /// Returns `(shortstatehash, already_existed)` fn get_or_create_shortstatehash(&self, state_hash: &[u8]) -> Result<(u64, bool)> { Ok(match self.statehash_shortstatehash.get(state_hash)? { Some(shortstatehash) => ( diff --git a/src/database/key_value/users.rs b/src/database/key_value/users.rs index 37b70e01..d2e1ef14 100644 --- a/src/database/key_value/users.rs +++ b/src/database/key_value/users.rs @@ -118,7 +118,7 @@ impl service::users::Data for KeyValueDatabase { } } - /// Returns the displayname of a user on this homeserver. + /// Returns the `displayname` of a user on this homeserver. fn displayname(&self, user_id: &UserId) -> Result> { self.userid_displayname .get(user_id.as_bytes())? @@ -129,7 +129,7 @@ impl service::users::Data for KeyValueDatabase { }) } - /// Sets a new displayname or removes it if displayname is None. You still need to nofify all rooms of this change. + /// Sets a new `displayname` or removes it if `displayname` is `None`. You still need to nofify all rooms of this change. fn set_displayname(&self, user_id: &UserId, displayname: Option) -> Result<()> { if let Some(displayname) = displayname { self.userid_displayname @@ -141,7 +141,7 @@ impl service::users::Data for KeyValueDatabase { Ok(()) } - /// Get the avatar_url of a user. + /// Get the `avatar_url` of a user. fn avatar_url(&self, user_id: &UserId) -> Result> { self.userid_avatarurl .get(user_id.as_bytes())? @@ -153,7 +153,7 @@ impl service::users::Data for KeyValueDatabase { .transpose() } - /// Sets a new avatar_url or removes it if avatar_url is None. + /// Sets a new `avatar_url` or removes it if `avatar_url` is `None`. fn set_avatar_url(&self, user_id: &UserId, avatar_url: Option) -> Result<()> { if let Some(avatar_url) = avatar_url { self.userid_avatarurl @@ -165,7 +165,7 @@ impl service::users::Data for KeyValueDatabase { Ok(()) } - /// Get the blurhash of a user. + /// Get the `blurhash` of a user. fn blurhash(&self, user_id: &UserId) -> Result> { self.userid_blurhash .get(user_id.as_bytes())? @@ -178,7 +178,7 @@ impl service::users::Data for KeyValueDatabase { .transpose() } - /// Sets a new avatar_url or removes it if avatar_url is None. + /// Sets a new `avatar_url` or removes it if `avatar_url` is `None`. fn set_blurhash(&self, user_id: &UserId, blurhash: Option) -> Result<()> { if let Some(blurhash) = blurhash { self.userid_blurhash @@ -954,7 +954,7 @@ impl service::users::Data for KeyValueDatabase { /// Will only return with Some(username) if the password was not empty and the /// username could be successfully parsed. -/// If utils::string_from_bytes(...) returns an error that username will be skipped +/// If [`utils::string_from_bytes`] returns an error that username will be skipped /// and the error will be logged. fn get_username_with_valid_password(username: &[u8], password: &[u8]) -> Option { // A valid password is not empty diff --git a/src/service/media/data.rs b/src/service/media/data.rs index ce2fc76c..0aea3f9d 100644 --- a/src/service/media/data.rs +++ b/src/service/media/data.rs @@ -10,7 +10,7 @@ pub(crate) trait Data: Send + Sync { content_type: Option<&str>, ) -> Result>; - /// Returns content_disposition, content_type and the metadata key. + /// Returns `content_disposition`, `content_type` and the `metadata` key. fn search_file_metadata( &self, mxc: String, diff --git a/src/service/rooms/edus/read_receipt/data.rs b/src/service/rooms/edus/read_receipt/data.rs index c25af24e..366e946c 100644 --- a/src/service/rooms/edus/read_receipt/data.rs +++ b/src/service/rooms/edus/read_receipt/data.rs @@ -10,7 +10,7 @@ pub(crate) trait Data: Send + Sync { event: ReceiptEvent, ) -> Result<()>; - /// Returns an iterator over the most recent read_receipts in a room that happened after the event with id `since`. + /// Returns an iterator over the most recent read receipts in a room that happened after the event with id `since`. #[allow(clippy::type_complexity)] fn readreceipts_since<'a>( &'a self, diff --git a/src/service/rooms/edus/typing.rs b/src/service/rooms/edus/typing.rs index 873736da..44d3e6af 100644 --- a/src/service/rooms/edus/typing.rs +++ b/src/service/rooms/edus/typing.rs @@ -12,7 +12,7 @@ pub(crate) struct Service { } impl Service { - /// Sets a user as typing until the timeout timestamp is reached or roomtyping_remove is + /// Sets a user as typing until the timeout timestamp is reached or `roomtyping_remove` is /// called. pub(crate) async fn typing_add( &self, diff --git a/src/service/rooms/short.rs b/src/service/rooms/short.rs index b2ad4fc5..f8d5be16 100644 --- a/src/service/rooms/short.rs +++ b/src/service/rooms/short.rs @@ -42,7 +42,7 @@ impl Service { self.db.get_statekey_from_short(shortstatekey) } - /// Returns (shortstatehash, already_existed) + /// Returns `(shortstatehash, already_existed)` pub(crate) fn get_or_create_shortstatehash(&self, state_hash: &[u8]) -> Result<(u64, bool)> { self.db.get_or_create_shortstatehash(state_hash) } diff --git a/src/service/rooms/short/data.rs b/src/service/rooms/short/data.rs index 2b7465f1..295f11a2 100644 --- a/src/service/rooms/short/data.rs +++ b/src/service/rooms/short/data.rs @@ -22,7 +22,7 @@ pub(crate) trait Data: Send + Sync { fn get_statekey_from_short(&self, shortstatekey: u64) -> Result<(StateEventType, String)>; - /// Returns (shortstatehash, already_existed) + /// Returns `(shortstatehash, already_existed)` fn get_or_create_shortstatehash(&self, state_hash: &[u8]) -> Result<(u64, bool)>; fn get_shortroomid(&self, room_id: &RoomId) -> Result>; diff --git a/src/service/rooms/state/data.rs b/src/service/rooms/state/data.rs index b8dda66b..1074a5dd 100644 --- a/src/service/rooms/state/data.rs +++ b/src/service/rooms/state/data.rs @@ -7,7 +7,7 @@ pub(crate) trait Data: Send + Sync { /// Returns the last state hash key added to the db for the given room. fn get_room_shortstatehash(&self, room_id: &RoomId) -> Result>; - /// Set the state hash to a new version, but does not update state_cache. + /// Set the state hash to a new version, but does not update `state_cache`. fn set_room_state( &self, room_id: &RoomId, @@ -18,7 +18,7 @@ pub(crate) trait Data: Send + Sync { /// Associates a state with an event. fn set_event_state(&self, shorteventid: u64, shortstatehash: u64) -> Result<()>; - /// Returns all events we would send as the prev_events of the next event. + /// Returns all events we would send as the `prev_events` of the next event. fn get_forward_extremities(&self, room_id: &RoomId) -> Result>>; /// Replace the forward extremities of the room. diff --git a/src/service/users.rs b/src/service/users.rs index 282663ea..b63e90bb 100644 --- a/src/service/users.rs +++ b/src/service/users.rs @@ -327,12 +327,12 @@ impl Service { self.db.set_displayname(user_id, displayname) } - /// Get the avatar_url of a user. + /// Get the `avatar_url` of a user. pub(crate) fn avatar_url(&self, user_id: &UserId) -> Result> { self.db.avatar_url(user_id) } - /// Sets a new avatar_url or removes it if avatar_url is None. + /// Sets a new `avatar_url` or removes it if `avatar_url` is `None`. pub(crate) fn set_avatar_url( &self, user_id: &UserId, @@ -341,12 +341,12 @@ impl Service { self.db.set_avatar_url(user_id, avatar_url) } - /// Get the blurhash of a user. + /// Get the `blurhash` of a user. pub(crate) fn blurhash(&self, user_id: &UserId) -> Result> { self.db.blurhash(user_id) } - /// Sets a new avatar_url or removes it if avatar_url is None. + /// Sets a new `avatar_url` or removes it if `avatar_url` is `None`. pub(crate) fn set_blurhash(&self, user_id: &UserId, blurhash: Option) -> Result<()> { self.db.set_blurhash(user_id, blurhash) } diff --git a/src/service/users/data.rs b/src/service/users/data.rs index 7a9b2610..3a7af883 100644 --- a/src/service/users/data.rs +++ b/src/service/users/data.rs @@ -39,19 +39,19 @@ pub(crate) trait Data: Send + Sync { /// Returns the displayname of a user on this homeserver. fn displayname(&self, user_id: &UserId) -> Result>; - /// Sets a new displayname or removes it if displayname is None. You still need to nofify all rooms of this change. + /// Sets a new `displayname` or removes it if `displayname` is `None`. You still need to nofify all rooms of this change. fn set_displayname(&self, user_id: &UserId, displayname: Option) -> Result<()>; - /// Get the avatar_url of a user. + /// Get the `avatar_url` of a user. fn avatar_url(&self, user_id: &UserId) -> Result>; - /// Sets a new avatar_url or removes it if avatar_url is None. + /// Sets a new `avatar_url` or removes it if `avatar_url` is `None`. fn set_avatar_url(&self, user_id: &UserId, avatar_url: Option) -> Result<()>; - /// Get the blurhash of a user. + /// Get the `blurhash` of a user. fn blurhash(&self, user_id: &UserId) -> Result>; - /// Sets a new avatar_url or removes it if avatar_url is None. + /// Sets a new `avatar_url` or removes it if `avatar_url` is `None`. fn set_blurhash(&self, user_id: &UserId, blurhash: Option) -> Result<()>; /// Adds a new device to a user.