docs: Document compat feature uses

2021-04-07 12:47:44 +02:00 · 2021-04-07 12:47:44 +02:00 · 154f9b2d58
commit 154f9b2d58
parent 2f406e63a4
21 changed files with 93 additions and 0 deletions
--- a/ruma-client-api/src/r0/account/request_3pid_management_token_via_email.rs
+++ b/ruma-client-api/src/r0/account/request_3pid_management_token_via_email.rs
@ -40,6 +40,9 @@ ruma_api! {
        pub sid: String,

        /// URL to submit validation token to. If omitted, verification happens without client.
+        ///
+        /// If you activate the `compat` feature, this field being an empty string in JSON will give
+        /// you `None` here.
        #[serde(skip_serializing_if = "Option::is_none")]
        #[cfg_attr(
            feature = "compat",
--- a/ruma-client-api/src/r0/account/request_3pid_management_token_via_msisdn.rs
+++ b/ruma-client-api/src/r0/account/request_3pid_management_token_via_msisdn.rs
@ -43,6 +43,9 @@ ruma_api! {
        pub sid: String,

        /// URL to submit validation token to. If omitted, verification happens without client.
+        ///
+        /// If you activate the `compat` feature, this field being an empty string in JSON will give
+        /// you `None` here.
        #[serde(skip_serializing_if = "Option::is_none")]
        #[cfg_attr(
            feature = "compat",
--- a/ruma-client-api/src/r0/account/request_password_change_token_via_email.rs
+++ b/ruma-client-api/src/r0/account/request_password_change_token_via_email.rs
@ -40,6 +40,9 @@ ruma_api! {
        pub sid: String,

        /// URL to submit validation token to. If omitted, verification happens without client.
+        ///
+        /// If you activate the `compat` feature, this field being an empty string in JSON will give
+        /// you `None` here.
        #[serde(skip_serializing_if = "Option::is_none")]
        #[cfg_attr(
            feature = "compat",
--- a/ruma-client-api/src/r0/account/request_password_change_token_via_msisdn.rs
+++ b/ruma-client-api/src/r0/account/request_password_change_token_via_msisdn.rs
@ -36,6 +36,9 @@ ruma_api! {
        pub sid: String,

        /// URL to submit validation token to. If omitted, verification happens without client.
+        ///
+        /// If you activate the `compat` feature, this field being an empty string in JSON will give
+        /// you `None` here.
        #[serde(skip_serializing_if = "Option::is_none")]
        #[cfg_attr(
            feature = "compat",
--- a/ruma-client-api/src/r0/account/request_registration_token_via_email.rs
+++ b/ruma-client-api/src/r0/account/request_registration_token_via_email.rs
@ -40,6 +40,9 @@ ruma_api! {
        pub sid: String,

        /// URL to submit validation token to. If omitted, verification happens without client.
+        ///
+        /// If you activate the `compat` feature, this field being an empty string in JSON will give
+        /// you `None` here.
        #[serde(skip_serializing_if = "Option::is_none")]
        #[cfg_attr(
            feature = "compat",
--- a/ruma-client-api/src/r0/account/request_registration_token_via_msisdn.rs
+++ b/ruma-client-api/src/r0/account/request_registration_token_via_msisdn.rs
@ -43,6 +43,9 @@ ruma_api! {
        pub sid: String,

        /// URL to submit validation token to. If omitted, verification happens without client.
+        ///
+        /// If you activate the `compat` feature, this field being an empty string in JSON will give
+        /// you `None` here.
        #[serde(skip_serializing_if = "Option::is_none")]
        #[cfg_attr(
            feature = "compat",
--- a/ruma-client-api/src/r0/directory.rs
+++ b/ruma-client-api/src/r0/directory.rs
@ -44,6 +44,9 @@ pub struct PublicRoomsChunk {
    pub guest_can_join: bool,

    /// The URL for the room's avatar, if one is set.
+    ///
+    /// If you activate the `compat` feature, this field being an empty string in JSON will give
+    /// you `None` here.
    #[serde(skip_serializing_if = "Option::is_none")]
    #[cfg_attr(
        feature = "compat",
--- a/ruma-client-api/src/r0/membership/joined_members.rs
+++ b/ruma-client-api/src/r0/membership/joined_members.rs
@ -54,6 +54,9 @@ pub struct RoomMember {
    pub display_name: Option<String>,

    /// The mxc avatar url of the user.
+    ///
+    /// If you activate the `compat` feature, this field being an empty string in JSON will give
+    /// you `None` here.
    #[serde(skip_serializing_if = "Option::is_none")]
    #[cfg_attr(
        feature = "compat",
--- a/ruma-client-api/src/r0/profile/get_avatar_url.rs
+++ b/ruma-client-api/src/r0/profile/get_avatar_url.rs
@ -25,6 +25,9 @@ ruma_api! {
    #[derive(Default)]
    response: {
        /// The user's avatar URL, if set.
+        ///
+        /// If you activate the `compat` feature, this field being an empty string in JSON will give
+        /// you `None` here.
        #[serde(skip_serializing_if = "Option::is_none")]
        #[cfg_attr(
            feature = "compat",
--- a/ruma-client-api/src/r0/profile/get_profile.rs
+++ b/ruma-client-api/src/r0/profile/get_profile.rs
@ -25,6 +25,9 @@ ruma_api! {
    #[derive(Default)]
    response: {
        /// The user's avatar URL, if set.
+        ///
+        /// If you activate the `compat` feature, this field being an empty string in JSON will give
+        /// you `None` here.
        #[serde(skip_serializing_if = "Option::is_none")]
        #[cfg_attr(
            feature = "compat",
--- a/ruma-client-api/src/r0/profile/set_avatar_url.rs
+++ b/ruma-client-api/src/r0/profile/set_avatar_url.rs
@ -21,6 +21,9 @@ ruma_api! {
        /// The new avatar URL for the user.
        ///
        /// `None` is used to unset the avatar.
+        ///
+        /// If you activate the `compat` feature, this field being an empty string in JSON will give
+        /// you `None` here.
        #[serde(skip_serializing_if = "Option::is_none")]
        #[cfg_attr(
            feature = "compat",
--- a/ruma-client-api/src/r0/search/search_events.rs
+++ b/ruma-client-api/src/r0/search/search_events.rs
@ -436,6 +436,9 @@ impl SearchResult {
 #[cfg_attr(not(feature = "unstable-exhaustive-types"), non_exhaustive)]
 pub struct UserProfile {
    /// The user's avatar URL, if set.
+    ///
+    /// If you activate the `compat` feature, this field being an empty string in JSON will give
+    /// you `None` here.
    #[serde(skip_serializing_if = "Option::is_none")]
    #[cfg_attr(
        feature = "compat",
--- a/ruma-client-api/src/r0/user_directory/search_users.rs
+++ b/ruma-client-api/src/r0/user_directory/search_users.rs
@ -78,6 +78,9 @@ pub struct User {
    pub display_name: Option<String>,

    /// The avatar url, as an MXC, if one exists.
+    ///
+    /// If you activate the `compat` feature, this field being an empty string in JSON will give
+    /// you `None` here.
    #[serde(skip_serializing_if = "Option::is_none")]
    #[cfg_attr(
        feature = "compat",
--- a/ruma-common/src/directory.rs
+++ b/ruma-common/src/directory.rs
@ -50,6 +50,9 @@ pub struct PublicRoomsChunk {
    pub guest_can_join: bool,

    /// The URL for the room's avatar, if one is set.
+    ///
+    /// If you activate the `compat` feature, this field being an empty string in JSON will give
+    /// you `None` here.
    #[serde(skip_serializing_if = "Option::is_none")]
    #[cfg_attr(
        feature = "compat",
--- a/ruma-common/src/power_levels.rs
+++ b/ruma-common/src/power_levels.rs
@ -10,6 +10,9 @@ use serde::{Deserialize, Serialize};
 #[cfg_attr(not(feature = "unstable-exhaustive-types"), non_exhaustive)]
 pub struct NotificationPowerLevels {
    /// The level required to trigger an `@room` notification.
+    ///
+    /// If you activate the `compat` feature, this field being a string in JSON will give
+    /// you an `Int` here.
    #[cfg_attr(feature = "compat", serde(deserialize_with = "ruma_serde::int_or_string_to_int"))]
    #[serde(default = "default_power_level")]
    pub room: Int,
--- a/ruma-events/src/presence.rs
+++ b/ruma-events/src/presence.rs
@ -26,6 +26,9 @@ pub struct PresenceEvent {
 #[ruma_event(type = "m.presence")]
 pub struct PresenceEventContent {
    /// The current avatar URL for this user.
+    ///
+    /// If you activate the `compat` feature, this field being an empty string in JSON will give
+    /// you `None` here.
    #[serde(skip_serializing_if = "Option::is_none")]
    #[cfg_attr(
        feature = "compat",
--- a/ruma-events/src/room/member.rs
+++ b/ruma-events/src/room/member.rs
@ -41,6 +41,9 @@ pub type MemberEvent = StateEvent<MemberEventContent>;
 #[ruma_event(type = "m.room.member")]
 pub struct MemberEventContent {
    /// The avatar URL for this user, if any. This is added by the homeserver.
+    ///
+    /// If you activate the `compat` feature, this field being an empty string in JSON will give
+    /// you `None` here.
    #[serde(skip_serializing_if = "Option::is_none")]
    #[cfg_attr(
        feature = "compat",
--- a/ruma-events/src/room/power_levels.rs
+++ b/ruma-events/src/room/power_levels.rs
@ -20,6 +20,9 @@ pub type PowerLevelsEvent = StateEvent<PowerLevelsEventContent>;
 #[ruma_event(type = "m.room.power_levels")]
 pub struct PowerLevelsEventContent {
    /// The level required to ban a user.
+    ///
+    /// If you activate the `compat` feature, this field being a string in JSON will give
+    /// you an `Int` here.
    #[cfg_attr(feature = "compat", serde(deserialize_with = "ruma_serde::int_or_string_to_int"))]
    #[serde(default = "default_power_level", skip_serializing_if = "is_default_power_level")]
    #[ruma_event(skip_redaction)]
@ -28,6 +31,9 @@ pub struct PowerLevelsEventContent {
    /// The level required to send specific event types.
    ///
    /// This is a mapping from event type to power level required.
+    ///
+    /// If you activate the `compat` feature, the value being a string in JSON will give
+    /// you an `Int` here.
    #[cfg_attr(
        feature = "compat",
        serde(deserialize_with = "ruma_serde::btreemap_int_or_string_to_int_values")
@ -37,29 +43,44 @@ pub struct PowerLevelsEventContent {
    pub events: BTreeMap<EventType, Int>,

    /// The default level required to send message events.
+    ///
+    /// If you activate the `compat` feature, this field being a string in JSON will give
+    /// you an `Int` here.
    #[cfg_attr(feature = "compat", serde(deserialize_with = "ruma_serde::int_or_string_to_int"))]
    #[serde(default, skip_serializing_if = "ruma_serde::is_default")]
    #[ruma_event(skip_redaction)]
    pub events_default: Int,

    /// The level required to invite a user.
+    ///
+    /// If you activate the `compat` feature, this field being a string in JSON will give
+    /// you an `Int` here.
    #[cfg_attr(feature = "compat", serde(deserialize_with = "ruma_serde::int_or_string_to_int"))]
    #[serde(default = "default_power_level", skip_serializing_if = "is_default_power_level")]
    pub invite: Int,

    /// The level required to kick a user.
+    ///
+    /// If you activate the `compat` feature, this field being a string in JSON will give
+    /// you an `Int` here.
    #[cfg_attr(feature = "compat", serde(deserialize_with = "ruma_serde::int_or_string_to_int"))]
    #[serde(default = "default_power_level", skip_serializing_if = "is_default_power_level")]
    #[ruma_event(skip_redaction)]
    pub kick: Int,

    /// The level required to redact an event.
+    ///
+    /// If you activate the `compat` feature, this field being a string in JSON will give
+    /// you an `Int` here.
    #[cfg_attr(feature = "compat", serde(deserialize_with = "ruma_serde::int_or_string_to_int"))]
    #[serde(default = "default_power_level", skip_serializing_if = "is_default_power_level")]
    #[ruma_event(skip_redaction)]
    pub redact: Int,

    /// The default level required to send state events.
+    ///
+    /// If you activate the `compat` feature, this field being a string in JSON will give
+    /// you an `Int` here.
    #[cfg_attr(feature = "compat", serde(deserialize_with = "ruma_serde::int_or_string_to_int"))]
    #[serde(default = "default_power_level", skip_serializing_if = "is_default_power_level")]
    #[ruma_event(skip_redaction)]
@ -68,6 +89,9 @@ pub struct PowerLevelsEventContent {
    /// The power levels for specific users.
    ///
    /// This is a mapping from `user_id` to power level for that user.
+    ///
+    /// If you activate the `compat` feature, the value being a string in JSON will give
+    /// you an `Int` here.
    #[cfg_attr(
        feature = "compat",
        serde(deserialize_with = "ruma_serde::btreemap_int_or_string_to_int_values")
@ -77,6 +101,9 @@ pub struct PowerLevelsEventContent {
    pub users: BTreeMap<UserId, Int>,

    /// The default power level for every user in the room.
+    ///
+    /// If you activate the `compat` feature, this field being a string in JSON will give
+    /// you an `Int` here.
    #[cfg_attr(feature = "compat", serde(deserialize_with = "ruma_serde::int_or_string_to_int"))]
    #[serde(default, skip_serializing_if = "ruma_serde::is_default")]
    #[ruma_event(skip_redaction)]
--- a/ruma-events/src/room/third_party_invite.rs
+++ b/ruma-events/src/room/third_party_invite.rs
@ -17,14 +17,23 @@ pub type ThirdPartyInviteEvent = StateEvent<ThirdPartyInviteEventContent>;
 #[ruma_event(type = "m.room.third_party_invite")]
 pub struct ThirdPartyInviteEventContent {
    /// A user-readable string which represents the user who has been invited.
+    ///
+    /// If you activate the `compat` feature, this field being absent in JSON will give you an
+    /// empty string here.
    #[cfg_attr(feature = "compat", serde(default))]
    pub display_name: String,

    /// A URL which can be fetched to validate whether the key has been revoked.
+    ///
+    /// If you activate the `compat` feature, this field being absent in JSON will give you an
+    /// empty string here.
    #[cfg_attr(feature = "compat", serde(default))]
    pub key_validity_url: String,

    /// A Base64-encoded Ed25519 key with which the token must be signed.
+    ///
+    /// If you activate the `compat` feature, this field being absent in JSON will give you an
+    /// empty string here.
    #[cfg_attr(feature = "compat", serde(default))]
    pub public_key: String,

--- a/ruma-events/src/room/tombstone.rs
+++ b/ruma-events/src/room/tombstone.rs
@ -15,6 +15,9 @@ pub type TombstoneEvent = StateEvent<TombstoneEventContent>;
 #[ruma_event(type = "m.room.tombstone")]
 pub struct TombstoneEventContent {
    /// A server-defined message.
+    ///
+    /// If you activate the `compat` feature, this field being absent in JSON will give you an
+    /// empty string here.
    #[cfg_attr(feature = "compat", serde(default))]
    pub body: String,

--- a/ruma-federation-api/src/query/get_profile_information/v1.rs
+++ b/ruma-federation-api/src/query/get_profile_information/v1.rs
@ -32,6 +32,9 @@ ruma_api! {
        pub displayname: Option<String>,

        /// Avatar URL for the user's avatar.
+        ///
+        /// If you activate the `compat` feature, this field being an empty string in JSON will give
+        /// you `None` here.
        #[serde(skip_serializing_if = "Option::is_none")]
        #[cfg_attr(
            feature = "compat",