docs: Improve string enums documentation

Mention the conversion from string.

crates/ruma-client-api/src/account.rs

@@ -44,9 +44,7 @@ impl<'a> IdentityServerInfo<'a> {
 }
 
 /// Possible values for deleting or unbinding 3PIDs.
-///
+#[doc = include_str!(concat!(env!("CARGO_MANIFEST_DIR"), "/src/doc/string_enum.md"))]
-/// This type can hold an arbitrary string. To check for formats that are not available as a
-/// documented variant here, use its string representation, obtained through `.as_str()`.
 #[derive(Clone, Debug, StringEnum)]
 #[ruma_enum(rename_all = "kebab-case")]
 #[non_exhaustive]

crates/ruma-client-api/src/discovery/get_capabilities.rs

@@ -197,9 +197,7 @@ impl Default for RoomVersionsCapability {
 }
 
 /// The stability of a room version.
-///
+#[doc = include_str!(concat!(env!("CARGO_MANIFEST_DIR"), "/src/doc/string_enum.md"))]
-/// This type can hold an arbitrary string. To check for formats that are not available as a
-/// documented variant here, use its string representation, obtained through `.as_str()`.
 #[derive(Clone, Debug, PartialEq, Eq, StringEnum)]
 #[ruma_enum(rename_all = "lowercase")]
 #[non_exhaustive]

crates/ruma-client-api/src/doc/string_enum.md

@@ -0,0 +1,4 @@
+<!-- Keep this comment so the content is always included as a new paragraph -->
+This type can hold an arbitrary string. To build this with a custom value, convert it from a
+string with `::from()` / `.into()`. To check for formats that are not available as a
+documented variant here, use its string representation, obtained through `.as_str()`.

crates/ruma-client-api/src/filter.rs

@@ -18,9 +18,7 @@ use crate::PrivOwnedStr;
 pub use self::{lazy_load::LazyLoadOptions, url::UrlFilter};
 
 /// Format to use for returned events.
-///
+#[doc = include_str!(concat!(env!("CARGO_MANIFEST_DIR"), "/src/doc/string_enum.md"))]
-/// This type can hold an arbitrary string. To check for formats that are not available as a
-/// documented variant here, use its string representation, obtained through `.as_str()`.
 #[derive(Clone, Debug, PartialEq, Eq, StringEnum)]
 #[ruma_enum(rename_all = "snake_case")]
 #[non_exhaustive]
@@ -50,8 +48,9 @@ impl Default for EventFormat {
 
 /// Relation types as defined in `rel_type` of an `m.relates_to` field.
 ///
-/// This type can hold an arbitrary string. To check for formats that are not available as a
+/// This type can hold an arbitrary string. To build this with a custom value, convert it from a
-/// documented variant here, use its string representation, obtained through `.as_str()`.
+/// string with `::from() / .into()`. To check for formats that are not available as a documented
+/// variant here, use its string representation, obtained through `.as_str()`.
 #[derive(Clone, Debug, PartialEq, Eq, StringEnum)]
 #[cfg(feature = "unstable-msc3440")]
 #[non_exhaustive]

crates/ruma-client-api/src/keys/upload_signatures.rs

@@ -103,6 +103,7 @@ pub mod v3 {
     }
 
     /// Error code for signed key processing failures.
+    #[doc = include_str!(concat!(env!("CARGO_MANIFEST_DIR"), "/src/doc/string_enum.md"))]
     #[derive(Clone, Debug, PartialEq, Eq, StringEnum)]
     #[non_exhaustive]
     #[ruma_enum(rename_all = "M_MATRIX_ERROR_CASE")]

crates/ruma-client-api/src/media/get_content_thumbnail.rs

@@ -98,9 +98,7 @@ pub mod v3 {
     }
 
     /// The desired resizing method.
-    ///
+    #[doc = include_str!(concat!(env!("CARGO_MANIFEST_DIR"), "/src/doc/string_enum.md"))]
-    /// This type can hold an arbitrary string. To check for formats that are not available as a
-    /// documented variant here, use its string representation, obtained through `.as_str()`.
     #[derive(Clone, Debug, StringEnum)]
     #[ruma_enum(rename_all = "snake_case")]
     #[non_exhaustive]

crates/ruma-client-api/src/membership/get_member_events.rs

@@ -79,9 +79,7 @@ pub mod v3 {
     }
 
     /// The kind of membership events to filter for.
-    ///
+    #[doc = include_str!(concat!(env!("CARGO_MANIFEST_DIR"), "/src/doc/string_enum.md"))]
-    /// This type can hold an arbitrary string. To check for formats that are not available as a
-    /// documented variant here, use its string representation, obtained through `.as_str()`.
     #[derive(Clone, Debug, PartialEq, Eq, StringEnum)]
     #[ruma_enum(rename_all = "lowercase")]
     #[non_exhaustive]

crates/ruma-client-api/src/push.rs

@@ -165,9 +165,7 @@ impl TryFrom<PushRule> for ConditionalPushRule {
 }
 
 /// The kinds of push rules that are available.
-///
+#[doc = include_str!(concat!(env!("CARGO_MANIFEST_DIR"), "/src/doc/string_enum.md"))]
-/// This type can hold an arbitrary string. To check for formats that are not available as a
-/// documented variant here, use its string representation, obtained through `.as_str()`.
 #[derive(Clone, Debug, PartialEq, Eq, PartialOrd, Ord, StringEnum)]
 #[ruma_enum(rename_all = "snake_case")]
 #[non_exhaustive]
@@ -200,8 +198,9 @@ impl RuleKind {
 
 /// Which kind a pusher is.
 ///
-/// This type can hold an arbitrary string. To check for formats that are not available as a
+/// This type can hold an arbitrary string. To build this with a custom value, convert it from a
-/// documented variant here, use its string representation, obtained through `.as_str()`.
+/// string with `::from() / .into()`. To check for formats that are not available as a documented
+/// variant here, use its string representation, obtained through `.as_str()`.
 #[derive(Clone, Debug, PartialEq, Eq, StringEnum)]
 #[ruma_enum(rename_all = "snake_case")]
 #[non_exhaustive]

crates/ruma-client-api/src/room.rs

@@ -11,9 +11,7 @@ use ruma_common::serde::StringEnum;
 use crate::PrivOwnedStr;
 
 /// Whether or not a newly created room will be listed in the room directory.
-///
+#[doc = include_str!(concat!(env!("CARGO_MANIFEST_DIR"), "/src/doc/string_enum.md"))]
-/// This type can hold an arbitrary string. To check for formats that are not available as a
-/// documented variant here, use its string representation, obtained through `.as_str()`.
 #[derive(Clone, Debug, PartialEq, Eq, StringEnum)]
 #[ruma_enum(rename_all = "snake_case")]
 #[non_exhaustive]

crates/ruma-client-api/src/room/create_room.rs

@@ -185,9 +185,7 @@ pub mod v3 {
     }
 
     /// A convenience parameter for setting a few default state events.
-    ///
+    #[doc = include_str!(concat!(env!("CARGO_MANIFEST_DIR"), "/src/doc/string_enum.md"))]
-    /// This type can hold an arbitrary string. To check for formats that are not available as a
-    /// documented variant here, use its string representation, obtained through `.as_str()`.
     #[derive(Clone, Debug, PartialEq, Eq, StringEnum)]
     #[ruma_enum(rename_all = "snake_case")]
     #[non_exhaustive]

crates/ruma-client-api/src/search/search_events.rs

@@ -250,9 +250,7 @@ pub mod v3 {
     }
 
     /// The key within events to use for this grouping.
-    ///
+    #[doc = include_str!(concat!(env!("CARGO_MANIFEST_DIR"), "/src/doc/string_enum.md"))]
-    /// This type can hold an arbitrary string. To check for formats that are not available as a
-    /// documented variant here, use its string representation, obtained through `.as_str()`.
     #[derive(Clone, Debug, PartialEq, Eq, PartialOrd, Ord, StringEnum)]
     #[ruma_enum(rename_all = "snake_case")]
     #[non_exhaustive]
@@ -298,7 +296,8 @@ pub mod v3 {
 
     /// The keys to search for.
     ///
-    /// This type can hold an arbitrary string. To check for formats that are not available as a
+    /// This type can hold an arbitrary string. To build this with a custom value, convert it from a
+    /// string with `::from() / .into()`. To check for formats that are not available as a
     /// documented variant here, use its string representation, obtained through `.as_str()`.
     #[derive(Clone, Debug, PartialEq, Eq, StringEnum)]
     #[non_exhaustive]
@@ -327,6 +326,10 @@ pub mod v3 {
     }
 
     /// The order in which to search for results.
+    ///
+    /// This type can hold an arbitrary string. To build this with a custom value, convert it from a
+    /// string with `::from() / .into()`. To check for formats that are not available as a
+    /// documented variant here, use its string representation, obtained through `.as_str()`.
     #[derive(Clone, Debug, PartialEq, Eq, StringEnum)]
     #[cfg_attr(not(feature = "unstable-exhaustive-types"), non_exhaustive)]
     #[ruma_enum(rename_all = "snake_case")]

crates/ruma-client-api/src/session/get_login_types.rs

@@ -193,11 +193,10 @@ pub mod v3 {
     /// An SSO login identity provider brand identifier.
     ///
     /// The predefined ones can be found in the matrix-spec-proposals repo in a [separate
-    /// document][matrix-spec-proposals]. To use a custom brand string, simply use
+    /// document][matrix-spec-proposals].
-    /// `IdentityProviderBrand::from("custom-brand")` or `"custom-brand".into()` (if the type is
-    /// known from the surrounding context).
     ///
     /// [matrix-spec-proposals]: https://github.com/matrix-org/matrix-spec-proposals/blob/v1.1/informal/idp-brands.md
+    #[doc = include_str!(concat!(env!("CARGO_MANIFEST_DIR"), "/src/doc/string_enum.md"))]
     #[derive(Clone, Debug, PartialEq, Eq, StringEnum)]
     #[cfg_attr(not(feature = "unstable-exhaustive-types"), non_exhaustive)]
     pub enum IdentityProviderBrand {

crates/ruma-client-api/src/space.rs

@@ -140,9 +140,7 @@ impl From<SpaceHierarchyRoomsChunkInit> for SpaceHierarchyRoomsChunk {
 /// In contrast to the regular [`JoinRule`](ruma_common::events::room::join_rules::JoinRule), this
 /// enum does not hold the conditions for joining restricted rooms. Instead, the server is assumed
 /// to only return rooms the user is allowed to join in a space hierarchy listing response.
-///
+#[doc = include_str!(concat!(env!("CARGO_MANIFEST_DIR"), "/src/doc/string_enum.md"))]
-/// This type can hold an arbitrary string. To check for join rules that are not available as a
-/// documented variant here, use its string representation, obtained through `.as_str()`.
 #[derive(Clone, Debug, PartialEq, Eq, StringEnum)]
 #[ruma_enum(rename_all = "snake_case")]
 #[cfg_attr(not(feature = "unstable-exhaustive-types"), non_exhaustive)]

crates/ruma-client-api/src/uiaa.rs

@@ -302,6 +302,7 @@ impl<'de> Deserialize<'de> for IncomingAuthData {
 }
 
 /// The type of an authentication stage.
+#[doc = include_str!(concat!(env!("CARGO_MANIFEST_DIR"), "/src/doc/string_enum.md"))]
 #[derive(Clone, Debug, PartialEq, Eq, PartialOrd, Ord, StringEnum)]
 #[non_exhaustive]
 pub enum AuthType {

crates/ruma-common/src/authentication.rs

@@ -3,9 +3,7 @@
 use crate::{serde::StringEnum, PrivOwnedStr};
 
 /// Access token types.
-///
+#[doc = include_str!(concat!(env!("CARGO_MANIFEST_DIR"), "/src/doc/string_enum.md"))]
-/// This type can hold an arbitrary string. To check for formats that are not available as a
-/// documented variant here, use its string representation, obtained through `.as_str()`.
 #[derive(Clone, Debug, PartialEq, Eq, StringEnum)]
 #[non_exhaustive]
 pub enum TokenType {

crates/ruma-common/src/directory.rs

@@ -230,9 +230,7 @@ impl<'de> Visitor<'de> for RoomNetworkVisitor {
 }
 
 /// The rule used for users wishing to join a public room.
-///
+#[doc = include_str!(concat!(env!("CARGO_MANIFEST_DIR"), "/src/doc/string_enum.md"))]
-/// This type can hold an arbitrary string. To check for join rules that are not available as a
-/// documented variant here, use its string representation, obtained through `.as_str()`.
 #[derive(Clone, Debug, PartialEq, Eq, StringEnum)]
 #[ruma_enum(rename_all = "snake_case")]
 #[cfg_attr(not(feature = "unstable-exhaustive-types"), non_exhaustive)]

crates/ruma-common/src/doc/string_enum.md

@@ -0,0 +1,4 @@
+<!-- Keep this comment so the content is always included as a new paragraph -->
+This type can hold an arbitrary string. To build this with a custom value, convert it from a
+string with `::from()` / `.into()`. To check for formats that are not available as a
+documented variant here, use its string representation, obtained through `.as_str()`.

crates/ruma-common/src/encryption.rs

@@ -155,6 +155,7 @@ impl CrossSigningKey {
 }
 
 /// The usage of a cross signing key.
+#[doc = include_str!(concat!(env!("CARGO_MANIFEST_DIR"), "/src/doc/string_enum.md"))]
 #[derive(Clone, Debug, StringEnum)]
 #[cfg_attr(not(feature = "unstable-exhaustive-types"), non_exhaustive)]
 #[ruma_enum(rename_all = "snake_case")]

crates/ruma-common/src/events/call.rs

@@ -31,9 +31,7 @@ impl SessionDescription {
 }
 
 /// The type of VoIP session description.
-///
+#[doc = include_str!(concat!(env!("CARGO_MANIFEST_DIR"), "/src/doc/string_enum.md"))]
-/// This type can hold an arbitrary string. To check for formats that are not available as a
-/// documented variant here, use its string representation, obtained through `.as_str()`.
 #[derive(Clone, Debug, PartialEq, Eq, StringEnum)]
 #[ruma_enum(rename_all = "snake_case")]
 #[non_exhaustive]

crates/ruma-common/src/events/call/hangup.rs

@@ -39,9 +39,7 @@ impl CallHangupEventContent {
 /// Should not be provided when the user naturally ends or rejects the call. When there was an error
 /// in the call negotiation, this should be `ice_failed` for when ICE negotiation fails or
 /// `invite_timeout` for when the other party did not answer in time.
-///
+#[doc = include_str!(concat!(env!("CARGO_MANIFEST_DIR"), "/src/doc/string_enum.md"))]
-/// This type can hold an arbitrary string. To check for formats that are not available as a
-/// documented variant here, use its string representation, obtained through `.as_str()`.
 #[derive(Clone, Debug, PartialEq, Eq, StringEnum)]
 #[ruma_enum(rename_all = "snake_case")]
 #[non_exhaustive]

crates/ruma-common/src/events/key/verification.rs

@@ -21,9 +21,7 @@ pub mod request;
 pub mod start;
 
 /// A hash algorithm.
-///
+#[doc = include_str!(concat!(env!("CARGO_MANIFEST_DIR"), "/src/doc/string_enum.md"))]
-/// This type can hold an arbitrary string. To check for formats that are not available as a
-/// documented variant here, use its string representation, obtained through `.as_str()`.
 #[derive(Clone, Debug, PartialEq, Eq, StringEnum)]
 #[ruma_enum(rename_all = "snake_case")]
 #[non_exhaustive]
@@ -44,8 +42,9 @@ impl HashAlgorithm {
 
 /// A key agreement protocol.
 ///
-/// This type can hold an arbitrary string. To check for formats that are not available as a
+/// This type can hold an arbitrary string. To build this with a custom value, convert it from a
-/// documented variant here, use its string representation, obtained through `.as_str()`.
+/// string with `::from() / .into()`. To check for formats that are not available as a documented
+/// variant here, use its string representation, obtained through `.as_str()`.
 #[derive(Clone, Debug, PartialEq, Eq, StringEnum)]
 #[ruma_enum(rename_all = "kebab-case")]
 #[non_exhaustive]
@@ -69,8 +68,9 @@ impl KeyAgreementProtocol {
 
 /// A message authentication code algorithm.
 ///
-/// This type can hold an arbitrary string. To check for formats that are not available as a
+/// This type can hold an arbitrary string. To build this with a custom value, convert it from a
-/// documented variant here, use its string representation, obtained through `.as_str()`.
+/// string with `::from() / .into()`. To check for formats that are not available as a documented
+/// variant here, use its string representation, obtained through `.as_str()`.
 #[derive(Clone, Debug, PartialEq, Eq, StringEnum)]
 #[ruma_enum(rename_all = "kebab-case")]
 #[non_exhaustive]
@@ -94,8 +94,9 @@ impl MessageAuthenticationCode {
 
 /// A Short Authentication String method.
 ///
-/// This type can hold an arbitrary string. To check for formats that are not available as a
+/// This type can hold an arbitrary string. To build this with a custom value, convert it from a
-/// documented variant here, use its string representation, obtained through `.as_str()`.
+/// string with `::from() / .into()`. To check for formats that are not available as a documented
+/// variant here, use its string representation, obtained through `.as_str()`.
 #[derive(Clone, Debug, PartialEq, Eq, StringEnum)]
 #[ruma_enum(rename_all = "snake_case")]
 #[non_exhaustive]
@@ -135,8 +136,9 @@ impl Relation {
 
 /// A Short Authentication String (SAS) verification method.
 ///
-/// This type can hold an arbitrary string. To check for formats that are not available as a
+/// This type can hold an arbitrary string. To build this with a custom value, convert it from a
-/// documented variant here, use its string representation, obtained through `.as_str()`.
+/// string with `::from() / .into()`. To check for formats that are not available as a documented
+/// variant here, use its string representation, obtained through `.as_str()`.
 #[derive(Clone, Debug, PartialEq, Eq, StringEnum)]
 #[non_exhaustive]
 pub enum VerificationMethod {

crates/ruma-common/src/events/key/verification/cancel.rs

@@ -65,10 +65,7 @@ impl KeyVerificationCancelEventContent {
 /// An error code for why the process/request was cancelled by the user.
 ///
 /// Custom error codes should use the Java package naming convention.
-///
+#[doc = include_str!(concat!(env!("CARGO_MANIFEST_DIR"), "/src/doc/string_enum.md"))]
-/// This type can hold an arbitrary string. To check for events that are not
-/// available as a documented variant here, use its string representation,
-/// obtained through `.as_str()`.
 // FIXME: Add `m.foo_bar` as a naming scheme in StringEnum and remove rename attributes.
 #[derive(Clone, Debug, PartialEq, Eq, StringEnum)]
 #[non_exhaustive]

crates/ruma-common/src/events/location.rs

@@ -179,9 +179,7 @@ impl AssetContent {
 }
 
 /// The type of an asset.
-///
+#[doc = include_str!(concat!(env!("CARGO_MANIFEST_DIR"), "/src/doc/string_enum.md"))]
-/// This type can hold an arbitrary string. To check for formats that are not available as a
-/// documented variant here, use its string representation, obtained through `.as_str()`.
 #[derive(Clone, Debug, PartialEq, Eq, PartialOrd, Ord, StringEnum)]
 #[non_exhaustive]
 pub enum AssetType {

crates/ruma-common/src/events/policy/rule.rs

@@ -33,9 +33,7 @@ impl PolicyRuleEventContent {
 }
 
 /// The possible actions that can be taken.
-///
+#[doc = include_str!(concat!(env!("CARGO_MANIFEST_DIR"), "/src/doc/string_enum.md"))]
-/// This type can hold an arbitrary string. To check for formats that are not available as a
-/// documented variant here, use its string representation, obtained through `.as_str()`.
 #[derive(Clone, Debug, PartialEq, Eq, StringEnum)]
 #[non_exhaustive]
 pub enum Recommendation {

crates/ruma-common/src/events/room/guest_access.rs

@@ -29,9 +29,7 @@ impl RoomGuestAccessEventContent {
 }
 
 /// A policy for guest user access to a room.
-///
+#[doc = include_str!(concat!(env!("CARGO_MANIFEST_DIR"), "/src/doc/string_enum.md"))]
-/// This type can hold an arbitrary string. To check for formats that are not available as a
-/// documented variant here, use its string representation, obtained through `.as_str()`.
 #[derive(Clone, Debug, PartialEq, Eq, StringEnum)]
 #[ruma_enum(rename_all = "snake_case")]
 #[non_exhaustive]

crates/ruma-common/src/events/room/history_visibility.rs

@@ -28,9 +28,7 @@ impl RoomHistoryVisibilityEventContent {
 }
 
 /// Who can see a room's history.
-///
+#[doc = include_str!(concat!(env!("CARGO_MANIFEST_DIR"), "/src/doc/string_enum.md"))]
-/// This type can hold an arbitrary string. To check for formats that are not available as a
-/// documented variant here, use its string representation, obtained through `.as_str()`.
 #[derive(Clone, Debug, PartialEq, Eq, StringEnum)]
 #[ruma_enum(rename_all = "snake_case")]
 #[non_exhaustive]

crates/ruma-common/src/events/room/member.rs

@@ -187,9 +187,7 @@ impl RedactedEventContent for RedactedRoomMemberEventContent {
 }
 
 /// The membership state of a user.
-///
+#[doc = include_str!(concat!(env!("CARGO_MANIFEST_DIR"), "/src/doc/string_enum.md"))]
-/// This type can hold an arbitrary string. To check for formats that are not available as a
-/// documented variant here, use its string representation, obtained through `.as_str()`.
 #[derive(Clone, Debug, PartialEq, Eq, StringEnum)]
 #[ruma_enum(rename_all = "lowercase")]
 #[non_exhaustive]

crates/ruma-common/src/events/room/message.rs

@@ -1346,9 +1346,7 @@ impl ServerNoticeMessageEventContent {
 }
 
 /// Types of server notices.
-///
+#[doc = include_str!(concat!(env!("CARGO_MANIFEST_DIR"), "/src/doc/string_enum.md"))]
-/// This type can hold an arbitrary string. To check for formats that are not available as a
-/// documented variant here, use its string representation, obtained through `.as_str()`.
 #[derive(Clone, Debug, PartialEq, Eq, StringEnum)]
 #[non_exhaustive]
 pub enum ServerNoticeType {
@@ -1369,8 +1367,9 @@ impl ServerNoticeType {
 
 /// Types of usage limits.
 ///
-/// This type can hold an arbitrary string. To check for formats that are not available as a
+/// This type can hold an arbitrary string. To build this with a custom value, convert it from a
-/// documented variant here, use its string representation, obtained through `.as_str()`.
+/// string with `::from() / .into()`. To check for formats that are not available as a documented
+/// variant here, use its string representation, obtained through `.as_str()`.
 #[derive(Clone, Debug, PartialEq, Eq, StringEnum)]
 #[ruma_enum(rename_all = "snake_case")]
 #[non_exhaustive]
@@ -1394,8 +1393,9 @@ impl LimitType {
 
 /// The format for the formatted representation of a message body.
 ///
-/// This type can hold an arbitrary string. To check for formats that are not available as a
+/// This type can hold an arbitrary string. To build this with a custom value, convert it from a
-/// documented variant here, use its string representation, obtained through `.as_str()`.
+/// string with `::from() / .into()`. To check for formats that are not available as a documented
+/// variant here, use its string representation, obtained through `.as_str()`.
 #[derive(Clone, Debug, PartialEq, Eq, StringEnum)]
 #[non_exhaustive]
 pub enum MessageFormat {

crates/ruma-common/src/events/room/message/feedback.rs

@@ -33,9 +33,7 @@ impl RoomMessageFeedbackEventContent {
 }
 
 /// A type of feedback.
-///
+#[doc = include_str!(concat!(env!("CARGO_MANIFEST_DIR"), "/src/doc/string_enum.md"))]
-/// This type can hold an arbitrary string. To check for formats that are not available as a
-/// documented variant here, use its string representation, obtained through `.as_str()`.
 #[derive(Clone, Debug, PartialEq, Eq, StringEnum)]
 #[ruma_enum(rename_all = "snake_case")]
 #[non_exhaustive]

crates/ruma-common/src/events/room_key_request.rs

@@ -46,9 +46,7 @@ impl ToDeviceRoomKeyRequestEventContent {
 }
 
 /// A new key request or a cancellation of a previous request.
-///
+#[doc = include_str!(concat!(env!("CARGO_MANIFEST_DIR"), "/src/doc/string_enum.md"))]
-/// This type can hold an arbitrary string. To check for formats that are not available as a
-/// documented variant here, use its string representation, obtained through `.as_str()`.
 #[derive(Clone, Debug, PartialEq, Eq, StringEnum)]
 #[ruma_enum(rename_all = "snake_case")]
 #[non_exhaustive]

crates/ruma-common/src/events/secret/request.rs

@@ -110,6 +110,7 @@ impl TryFrom<RequestActionJsonRepr> for RequestAction {
 }
 
 /// The name of a secret.
+#[doc = include_str!(concat!(env!("CARGO_MANIFEST_DIR"), "/src/doc/string_enum.md"))]
 #[derive(Clone, Debug, PartialEq, Eq, PartialOrd, Ord, StringEnum)]
 #[cfg_attr(not(feature = "unstable-exhaustive-types"), non_exhaustive)]
 pub enum SecretName {

crates/ruma-common/src/identifiers/crypto_algorithms.rs

@@ -5,9 +5,7 @@ use ruma_macros::StringEnum;
 use crate::PrivOwnedStr;
 
 /// The basic key algorithms in the specification.
-///
+#[doc = include_str!(concat!(env!("CARGO_MANIFEST_DIR"), "/src/doc/string_enum.md"))]
-/// This type can hold an arbitrary string. To check for algorithms that are not available as a
-/// documented variant here, use its string representation, obtained through `.as_str()`.
 #[derive(Clone, Debug, PartialEq, Eq, PartialOrd, Ord, StringEnum)]
 #[non_exhaustive]
 #[ruma_enum(rename_all = "snake_case")]
@@ -26,9 +24,7 @@ pub enum DeviceKeyAlgorithm {
 }
 
 /// The signing key algorithms defined in the Matrix spec.
-///
+#[doc = include_str!(concat!(env!("CARGO_MANIFEST_DIR"), "/src/doc/string_enum.md"))]
-/// This type can hold an arbitrary string. To check for algorithms that are not available as a
-/// documented variant here, use its string representation, obtained through `.as_str()`.
 #[derive(Clone, Debug, PartialEq, Eq, PartialOrd, Ord, StringEnum)]
 #[non_exhaustive]
 #[ruma_enum(rename_all = "snake_case")]
@@ -41,9 +37,7 @@ pub enum SigningKeyAlgorithm {
 }
 
 /// An encryption algorithm to be used to encrypt messages sent to a room.
-///
+#[doc = include_str!(concat!(env!("CARGO_MANIFEST_DIR"), "/src/doc/string_enum.md"))]
-/// This type can hold an arbitrary string. To check for algorithms that are not available as a
-/// documented variant here, use its string representation, obtained through `.as_str()`.
 #[derive(Clone, Debug, PartialEq, Eq, PartialOrd, Ord, StringEnum)]
 #[non_exhaustive]
 pub enum EventEncryptionAlgorithm {

crates/ruma-common/src/presence.rs

@@ -5,9 +5,7 @@
 use crate::{serde::StringEnum, PrivOwnedStr};
 
 /// A description of a user's connectivity and availability for chat.
-///
+#[doc = include_str!(concat!(env!("CARGO_MANIFEST_DIR"), "/src/doc/string_enum.md"))]
-/// This type can hold an arbitrary string. To check for formats that are not available as a
-/// documented variant here, use its string representation, obtained through `.as_str()`.
 #[derive(Clone, Debug, PartialEq, Eq, StringEnum)]
 #[ruma_enum(rename_all = "snake_case")]
 #[non_exhaustive]

crates/ruma-common/src/push.rs

@@ -440,10 +440,8 @@ impl PusherData {
 /// A special format that the homeserver should use when sending notifications to a Push Gateway.
 /// Currently, only "event_id_only" is supported as of [Push Gateway API r0.1.1][spec].
 ///
-/// This type can hold an arbitrary string. To check for formats that are not available as a
-/// documented variant here, use its string representation, obtained through `.as_str()`.
-///
 /// [spec]: https://spec.matrix.org/v1.2/push-gateway-api/#homeserver-behaviour
+#[doc = include_str!(concat!(env!("CARGO_MANIFEST_DIR"), "/src/doc/string_enum.md"))]
 #[derive(Clone, Debug, PartialEq, Eq, StringEnum)]
 #[ruma_enum(rename_all = "snake_case")]
 #[non_exhaustive]

crates/ruma-common/src/receipt.rs

@@ -6,9 +6,7 @@ use crate::{
 };
 
 /// The type of receipt.
-///
+#[doc = include_str!(concat!(env!("CARGO_MANIFEST_DIR"), "/src/doc/string_enum.md"))]
-/// This type can hold an arbitrary string. To check for formats that are not available as a
-/// documented variant here, use its string representation, obtained through `.as_str()`.
 #[derive(Clone, Debug, PartialOrdAsRefStr, OrdAsRefStr, PartialEqAsRefStr, Eq, StringEnum)]
 #[non_exhaustive]
 pub enum ReceiptType {

crates/ruma-common/src/room.rs

@@ -3,9 +3,7 @@
 use crate::{serde::StringEnum, PrivOwnedStr};
 
 /// An enum of possible room types.
-///
+#[doc = include_str!(concat!(env!("CARGO_MANIFEST_DIR"), "/src/doc/string_enum.md"))]
-/// This type can hold an arbitrary string. To check for room types that are not available as a
-/// documented variant here, use its string representation, obtained through `.as_str()`.
 #[derive(Clone, Debug, PartialEq, Eq, StringEnum)]
 #[non_exhaustive]
 pub enum RoomType {

crates/ruma-common/src/thirdparty.rs

@@ -217,9 +217,7 @@ impl User {
 }
 
 /// The medium of a third party identifier.
-///
+#[doc = include_str!(concat!(env!("CARGO_MANIFEST_DIR"), "/src/doc/string_enum.md"))]
-/// This type can hold an arbitrary string. To check for formats that are not available as a
-/// documented variant here, use its string representation, obtained through `.as_str()`.
 #[derive(Clone, Debug, PartialEq, Eq, StringEnum)]
 #[ruma_enum(rename_all = "lowercase")]
 #[non_exhaustive]

crates/ruma-federation-api/src/query/get_profile_information.rs

@@ -80,7 +80,8 @@ pub mod v1 {
 
     /// Profile fields to specify in query.
     ///
-    /// This type can hold an arbitrary string. To check for formats that are not available as a
+    /// This type can hold an arbitrary string. To build this with a custom value, convert it from a
+    /// string with `::from() / .into()`. To check for formats that are not available as a
     /// documented variant here, use its string representation, obtained through `.as_str()`.
     #[derive(Clone, Debug, PartialEq, Eq, StringEnum)]
     #[non_exhaustive]

crates/ruma-identity-service-api/src/lookup.rs

@@ -10,8 +10,9 @@ pub mod lookup_3pid;
 /// The algorithms that can be used to hash the identifiers used for lookup, as defined in the
 /// Matrix Spec.
 ///
-/// This type can hold an arbitrary string. To check for algorithms that are not available as a
+/// This type can hold an arbitrary string. To build this with a custom value, convert it from a
-/// documented variant here, use its string representation, obtained through `.as_str()`.
+/// string with `::from() / .into()`. To check for formats that are not available as a documented
+/// variant here, use its string representation, obtained through `.as_str()`.
 #[derive(Debug, PartialEq, Eq, Clone, StringEnum)]
 #[non_exhaustive]
 #[ruma_enum(rename_all = "snake_case")]

crates/ruma-macros/src/events/event_type.rs

@@ -164,8 +164,9 @@ fn generate_enum(
     Ok(quote! {
         #[doc = #enum_doc]
         ///
-        /// This type can hold an arbitrary string. To check for events that are not available as a
+        /// This type can hold an arbitrary string. To build events with a custom type, convert it
-        /// documented variant here, use its string representation, obtained through `.as_str()`.
+        /// from a string with `::from() / .into()`. To check for events that are not available as a
+        /// documented variant here, use its string representation, obtained through `.to_string()`.
         #deprecated_attr
         #[derive(Debug, Clone, PartialEq, Eq, PartialOrd, Ord, Hash)]
         #[cfg_attr(not(feature = "unstable-exhaustive-types"), non_exhaustive)]

crates/ruma-push-gateway-api/src/send_event_notification.rs

@@ -145,7 +145,8 @@ pub mod v1 {
     /// This may be used by push gateways to deliver less time-sensitive
     /// notifications in a way that will preserve battery power on mobile devices.
     ///
-    /// This type can hold an arbitrary string. To check for formats that are not available as a
+    /// This type can hold an arbitrary string. To build this with a custom value, convert it from a
+    /// string with `::from() / .into()`. To check for formats that are not available as a
     /// documented variant here, use its string representation, obtained through `.as_str()`.
     #[derive(Clone, Debug, PartialEq, Eq, StringEnum)]
     #[ruma_enum(rename_all = "snake_case")]