From 02008ac6e94e5da3bb494716a027eb823396a9fd Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?K=C3=A9vin=20Commaille?= Date: Sat, 19 Feb 2022 12:38:24 +0100 Subject: [PATCH] identifiers: Add links to the spec for identifiers --- crates/ruma-identifiers/src/event_id.rs | 4 +++- crates/ruma-identifiers/src/matrix_uri.rs | 4 +++- crates/ruma-identifiers/src/room_alias_id.rs | 4 +++- crates/ruma-identifiers/src/room_id.rs | 4 +++- crates/ruma-identifiers/src/room_or_room_alias_id.rs | 5 ++++- crates/ruma-identifiers/src/room_version_id.rs | 4 +++- crates/ruma-identifiers/src/server_name.rs | 4 +++- crates/ruma-identifiers/src/user_id.rs | 4 +++- 8 files changed, 25 insertions(+), 8 deletions(-) diff --git a/crates/ruma-identifiers/src/event_id.rs b/crates/ruma-identifiers/src/event_id.rs index 89d6ac85..046c9d6f 100644 --- a/crates/ruma-identifiers/src/event_id.rs +++ b/crates/ruma-identifiers/src/event_id.rs @@ -2,7 +2,7 @@ use crate::ServerName; -/// A Matrix event ID. +/// A Matrix [event ID]. /// /// An `EventId` is generated randomly or converted from a string slice, and can be converted back /// into a string as needed. @@ -32,6 +32,8 @@ use crate::ServerName; /// "$Rqnc-F-dvnEYJTyHq_iKxU2bZ1CI92-kuZq3a5lr5Zg" /// ); /// ``` +/// +/// [event ID]: https://spec.matrix.org/v1.2/appendices/#room-ids-and-event-ids #[repr(transparent)] #[derive(PartialEq, Eq, PartialOrd, Ord, Hash)] pub struct EventId(str); diff --git a/crates/ruma-identifiers/src/matrix_uri.rs b/crates/ruma-identifiers/src/matrix_uri.rs index e28e96ce..9bb849de 100644 --- a/crates/ruma-identifiers/src/matrix_uri.rs +++ b/crates/ruma-identifiers/src/matrix_uri.rs @@ -159,10 +159,12 @@ impl From<(&RoomAliasId, &EventId)> for MatrixId { } } -/// The `matrix.to` URI representation of a user, room or event. +/// The [`matrix.to` URI] representation of a user, room or event. /// /// Get the URI through its `Display` implementation (i.e. by interpolating it /// in a formatting macro or via `.to_string()`). +/// +/// [`matrix.to` URI]: https://spec.matrix.org/v1.2/appendices/#matrixto-navigation #[derive(Debug, PartialEq, Eq)] pub struct MatrixToUri { id: MatrixId, diff --git a/crates/ruma-identifiers/src/room_alias_id.rs b/crates/ruma-identifiers/src/room_alias_id.rs index 2a86147c..0fee2fc0 100644 --- a/crates/ruma-identifiers/src/room_alias_id.rs +++ b/crates/ruma-identifiers/src/room_alias_id.rs @@ -2,7 +2,7 @@ use crate::{server_name::ServerName, EventId, MatrixToUri}; -/// A Matrix room alias ID. +/// A Matrix [room alias ID]. /// /// A `RoomAliasId` is converted from a string slice, and can be converted back into a string as /// needed. @@ -12,6 +12,8 @@ use crate::{server_name::ServerName, EventId, MatrixToUri}; /// # use ruma_identifiers::RoomAliasId; /// assert_eq!(<&RoomAliasId>::try_from("#ruma:example.com").unwrap(), "#ruma:example.com"); /// ``` +/// +/// [room alias ID]: https://spec.matrix.org/v1.2/appendices/#room-aliases #[repr(transparent)] #[derive(PartialEq, Eq, PartialOrd, Ord, Hash)] pub struct RoomAliasId(str); diff --git a/crates/ruma-identifiers/src/room_id.rs b/crates/ruma-identifiers/src/room_id.rs index c6df83aa..9c140387 100644 --- a/crates/ruma-identifiers/src/room_id.rs +++ b/crates/ruma-identifiers/src/room_id.rs @@ -2,7 +2,7 @@ use crate::{EventId, MatrixToUri, ServerName}; -/// A Matrix room ID. +/// A Matrix [room ID]. /// /// A `RoomId` is generated randomly or converted from a string slice, and can be converted back /// into a string as needed. @@ -12,6 +12,8 @@ use crate::{EventId, MatrixToUri, ServerName}; /// # use ruma_identifiers::RoomId; /// assert_eq!(<&RoomId>::try_from("!n8f893n9:example.com").unwrap(), "!n8f893n9:example.com"); /// ``` +/// +/// [room ID]: https://spec.matrix.org/v1.2/appendices/#room-ids-and-event-ids #[repr(transparent)] #[derive(PartialEq, Eq, PartialOrd, Ord, Hash)] pub struct RoomId(str); diff --git a/crates/ruma-identifiers/src/room_or_room_alias_id.rs b/crates/ruma-identifiers/src/room_or_room_alias_id.rs index 7144467c..a408a5ec 100644 --- a/crates/ruma-identifiers/src/room_or_room_alias_id.rs +++ b/crates/ruma-identifiers/src/room_or_room_alias_id.rs @@ -4,7 +4,7 @@ use std::{convert::TryFrom, hint::unreachable_unchecked}; use crate::{server_name::ServerName, RoomAliasId, RoomId}; -/// A Matrix room ID or a Matrix room alias ID. +/// A Matrix [room ID] or a Matrix [room alias ID]. /// /// `RoomOrAliasId` is useful for APIs that accept either kind of room identifier. It is converted /// from a string slice, and can be converted back into a string as needed. When converted from a @@ -20,6 +20,9 @@ use crate::{server_name::ServerName, RoomAliasId, RoomId}; /// "!n8f893n9:example.com" /// ); /// ``` +/// +/// [room ID]: https://spec.matrix.org/v1.2/appendices/#room-ids-and-event-ids +/// [room alias ID]: https://spec.matrix.org/v1.2/appendices/#room-aliases #[repr(transparent)] #[derive(PartialEq, Eq, PartialOrd, Ord, Hash)] pub struct RoomOrAliasId(str); diff --git a/crates/ruma-identifiers/src/room_version_id.rs b/crates/ruma-identifiers/src/room_version_id.rs index 65e33398..54b821ed 100644 --- a/crates/ruma-identifiers/src/room_version_id.rs +++ b/crates/ruma-identifiers/src/room_version_id.rs @@ -6,7 +6,7 @@ use ruma_serde_macros::DisplayAsRefStr; #[cfg(feature = "serde")] use serde::{Deserialize, Deserializer, Serialize, Serializer}; -/// A Matrix room version ID. +/// A Matrix [room version] ID. /// /// A `RoomVersionId` can be or converted or deserialized from a string slice, and can be converted /// or serialized back into a string as needed. @@ -21,6 +21,8 @@ use serde::{Deserialize, Deserializer, Serialize, Serializer}; /// Custom room versions or ones that were introduced into the specification after this code was /// written are represented by a hidden enum variant. You can still construct them the same, and /// check for them using one of `RoomVersionId`s `PartialEq` implementations or through `.as_str()`. +/// +/// [room version]: https://spec.matrix.org/v1.2/rooms/ #[derive(Clone, Debug, PartialEq, Eq, Hash, DisplayAsRefStr)] #[cfg_attr(not(feature = "unstable-exhaustive-types"), non_exhaustive)] pub enum RoomVersionId { diff --git a/crates/ruma-identifiers/src/server_name.rs b/crates/ruma-identifiers/src/server_name.rs index 0ff0a20b..675ca52b 100644 --- a/crates/ruma-identifiers/src/server_name.rs +++ b/crates/ruma-identifiers/src/server_name.rs @@ -2,9 +2,11 @@ use std::net::Ipv4Addr; -/// A Matrix-spec compliant server name. +/// A Matrix-spec compliant [server name]. /// /// It consists of a host and an optional port (separated by a colon if present). +/// +/// [server name]: https://spec.matrix.org/v1.2/appendices/#server-name #[repr(transparent)] #[derive(PartialEq, Eq, PartialOrd, Ord, Hash)] pub struct ServerName(str); diff --git a/crates/ruma-identifiers/src/user_id.rs b/crates/ruma-identifiers/src/user_id.rs index 63a6dcb6..2abeccf5 100644 --- a/crates/ruma-identifiers/src/user_id.rs +++ b/crates/ruma-identifiers/src/user_id.rs @@ -4,7 +4,7 @@ use std::{rc::Rc, sync::Arc}; use crate::{MatrixToUri, ServerName}; -/// A Matrix user ID. +/// A Matrix [user ID]. /// /// A `UserId` is generated randomly or converted from a string slice, and can be converted back /// into a string as needed. @@ -14,6 +14,8 @@ use crate::{MatrixToUri, ServerName}; /// # use ruma_identifiers::UserId; /// assert_eq!(<&UserId>::try_from("@carl:example.com").unwrap(), "@carl:example.com"); /// ``` +/// +/// [user ID]: https://spec.matrix.org/v1.2/appendices/#user-identifiers #[repr(transparent)] #[derive(PartialEq, Eq, PartialOrd, Ord, Hash)] pub struct UserId(str);