Improve documentation

src/event_id.rs

@@ -9,6 +9,9 @@ use crate::{error::Error, parse_id, validate_id};
 /// An `EventId` is generated randomly or converted from a string slice, and can be converted back
 /// into a string as needed.
 ///
+/// It is discouraged to use this type directly – instead use one of the aliases (`EventId` and
+/// `EventIdRef`) in the crate root.
+///
 /// # Room versions
 ///
 /// Matrix specifies multiple [room versions](https://matrix.org/docs/spec/#room-versions) and the

src/lib.rs

@@ -34,33 +34,71 @@ pub mod room_version_id;
 pub mod user_id;
 
 /// An owned event ID.
+///
+/// Can be created via `new` (if the `rand` feature is enabled) and `TryFrom<String>` +
+/// `TryFrom<&str>`, implements `Serialize` and `Deserialize` if the `serde` feature is enabled.
 pub type EventId = event_id::EventId<Box<str>>;
+
 /// A reference to an event ID.
+///
+/// Can be created via `TryFrom<&str>`, implements `Serialize` if the `serde` feature is enabled.
 pub type EventIdRef<'a> = event_id::EventId<&'a str>;
 
 /// An owned room alias ID.
+///
+/// Can be created via `TryFrom<String>` and `TryFrom<&str>`, implements `Serialize` and
+/// `Deserialize` if the `serde` feature is enabled.
 pub type RoomAliasId = room_alias_id::RoomAliasId<Box<str>>;
+
 /// A reference to a room alias ID.
+///
+/// Can be created via `TryFrom<&str>`, implements `Serialize` if the `serde` feature is enabled.
 pub type RoomAliasIdRef<'a> = room_alias_id::RoomAliasId<&'a str>;
 
 /// An owned room ID.
+///
+/// Can be created via `new` (if the `rand` feature is enabled) and `TryFrom<String>` +
+/// `TryFrom<&str>`, implements `Serialize` and `Deserialize` if the `serde` feature is enabled.
 pub type RoomId = room_id::RoomId<Box<str>>;
+
 /// A reference to a room ID.
+///
+/// Can be created via `TryFrom<&str>`, implements `Serialize` if the `serde` feature is enabled.
 pub type RoomIdRef<'a> = room_id::RoomId<&'a str>;
 
 /// An owned room alias ID or room ID.
+///
+/// Can be created via `TryFrom<String>`, `TryFrom<&str>`, `From<RoomId>` and `From<RoomAliasId>`;
+/// implements `Serialize` and `Deserialize` if the `serde` feature is enabled.
 pub type RoomIdOrAliasId = room_id_or_room_alias_id::RoomIdOrAliasId<Box<str>>;
+
 /// A reference to a room alias ID or room ID.
+///
+/// Can be created via `TryFrom<&str>`, `From<RoomIdRef>` and `From<RoomAliasIdRef>`; implements
+/// `Serialize` if the `serde` feature is enabled.
 pub type RoomIdOrAliasIdRef<'a> = room_id_or_room_alias_id::RoomIdOrAliasId<&'a str>;
 
 /// An owned room version ID.
+///
+/// Can be created using the `version_N` constructor functions, `TryFrom<String>` and
+/// `TryFrom<&str>`; implements `Serialize` and `Deserialize` if the `serde` feature is enabled.
 pub type RoomVersionId = room_version_id::RoomVersionId<Box<str>>;
+
 /// A reference to a room version ID.
+///
+/// Can be created using the `version_N` constructor functions and via `TryFrom<&str>`, implements
+/// `Serialize` if the `serde` feature is enabled.
 pub type RoomVersionIdRef<'a> = room_version_id::RoomVersionId<&'a str>;
 
 /// An owned user ID.
+///
+/// Can be created via `new` (if the `rand` feature is enabled) and `TryFrom<String>` +
+/// `TryFrom<&str>`, implements `Serialize` and `Deserialize` if the `serde` feature is enabled.
 pub type UserId = user_id::UserId<Box<str>>;
+
 /// A reference to a user ID.
+///
+/// Can be created via `TryFrom<&str>`, implements `Serialize` if the `serde` feature is enabled.
 pub type UserIdRef<'a> = user_id::UserId<&'a str>;
 
 /// All identifiers must be 255 bytes or less.

src/room_alias_id.rs

@@ -6,6 +6,9 @@ use crate::{error::Error, parse_id};
 
 /// A Matrix room alias ID.
 ///
+/// It is discouraged to use this type directly – instead use one of the aliases (`RoomAliasId` and
+/// `RoomAliasIdRef`) in the crate root.
+///
 /// A `RoomAliasId` is converted from a string slice, and can be converted back into a string as
 /// needed.
 ///

src/room_id.rs

@@ -9,6 +9,9 @@ use crate::{error::Error, parse_id};
 /// A `RoomId` is generated randomly or converted from a string slice, and can be converted back
 /// into a string as needed.
 ///
+/// It is discouraged to use this type directly – instead use one of the aliases (`RoomId` and
+/// `RoomIdRef`) in the crate root.
+///
 /// ```
 /// # use std::convert::TryFrom;
 /// # use ruma_identifiers::RoomId;

src/room_id_or_room_alias_id.rs

@@ -10,6 +10,9 @@ use crate::{error::Error, parse_id, room_alias_id::RoomAliasId, room_id::RoomId}
 /// from a string slice, and can be converted back into a string as needed. When converted from a
 /// string slice, the variant is determined by the leading sigil character.
 ///
+/// It is discouraged to use this type directly – instead use one of the aliases
+/// (`RoomIdOrRoomAliasId` and `RoomIdOrRoomAliasIdRef`) in the crate root.
+///
 /// ```
 /// # use std::convert::TryFrom;
 /// # use ruma_identifiers::RoomIdOrAliasId;

src/room_version_id.rs

@@ -19,6 +19,9 @@ const MAX_CODE_POINTS: usize = 32;
 /// A `RoomVersionId` can be or converted or deserialized from a string slice, and can be converted
 /// or serialized back into a string as needed.
 ///
+/// It is discouraged to use this type directly – instead use one of the aliases (`RoomVersionId`
+/// and `RoomVersionIdRef`) in the crate root.
+///
 /// ```
 /// # use std::convert::TryFrom;
 /// # use ruma_identifiers::RoomVersionId;

src/user_id.rs

@@ -9,6 +9,9 @@ use crate::{error::Error, is_valid_server_name, parse_id};
 /// A `UserId` is generated randomly or converted from a string slice, and can be converted back
 /// into a string as needed.
 ///
+/// It is discouraged to use this type directly – instead use one of the aliases (`UserId` and
+/// `UserIdRef`) in the crate root.
+///
 /// ```
 /// # use std::convert::TryFrom;
 /// # use ruma_identifiers::UserId;