docs: Document uses of the unstable-pre-spec feature flag

ruma-client-api/src/lib.rs

@@ -6,6 +6,7 @@
 //! [client-api]: https://matrix.org/docs/spec/client_server/r0.6.1.html
 
 #![warn(missing_debug_implementations, missing_docs)]
+#![cfg_attr(docsrs, feature(doc_cfg))]
 
 pub mod error;
 pub mod r0;

ruma-client-api/src/r0/backup.rs

@@ -1,5 +1,6 @@
 //! Endpoints for server-side key backups.
 #![cfg(feature = "unstable-pre-spec")]
+#![cfg_attr(docsrs, doc(cfg(feature = "unstable-pre-spec")))]
 
 pub mod add_backup_key_session;
 pub mod add_backup_key_sessions;

ruma-client-api/src/r0/keys.rs

@@ -11,8 +11,10 @@ pub mod get_keys;
 pub mod upload_keys;
 
 #[cfg(feature = "unstable-pre-spec")]
+#[cfg_attr(docsrs, doc(cfg(feature = "unstable-pre-spec")))]
 pub mod upload_signatures;
 #[cfg(feature = "unstable-pre-spec")]
+#[cfg_attr(docsrs, doc(cfg(feature = "unstable-pre-spec")))]
 pub mod upload_signing_keys;
 
 /// Signatures for a `SignedKey` object.

ruma-client-api/src/r0/keys/get_keys.rs

@@ -58,16 +58,19 @@ ruma_api! {
 
         /// Information on the master cross-signing keys of the queried users.
         #[cfg(feature = "unstable-pre-spec")]
+        #[cfg_attr(docsrs, doc(cfg(feature = "unstable-pre-spec")))]
         #[serde(default, skip_serializing_if = "BTreeMap::is_empty")]
         pub master_keys: BTreeMap<UserId, CrossSigningKey>,
 
         /// Information on the self-signing keys of the queried users.
         #[cfg(feature = "unstable-pre-spec")]
+        #[cfg_attr(docsrs, doc(cfg(feature = "unstable-pre-spec")))]
         #[serde(default, skip_serializing_if = "BTreeMap::is_empty")]
         pub self_signing_keys: BTreeMap<UserId, CrossSigningKey>,
 
         /// Information on the user-signing keys of the queried users.
         #[cfg(feature = "unstable-pre-spec")]
+        #[cfg_attr(docsrs, doc(cfg(feature = "unstable-pre-spec")))]
         #[serde(default, skip_serializing_if = "BTreeMap::is_empty")]
         pub user_signing_keys: BTreeMap<UserId, CrossSigningKey>,
     }

ruma-client-api/src/r0/media/create_content.rs

@@ -37,6 +37,7 @@ ruma_api! {
         /// This uses the unstable prefix in
         /// [MSC2448](https://github.com/matrix-org/matrix-doc/pull/2448).
         #[cfg(feature = "unstable-pre-spec")]
+        #[cfg_attr(docsrs, doc(cfg(feature = "unstable-pre-spec")))]
         #[serde(rename = "xyz.amorgan.blurhash")]
         #[serde(skip_serializing_if = "Option::is_none")]
         pub blurhash: Option<String>,

ruma-common/src/lib.rs

@@ -3,6 +3,7 @@
 //! Common types for other ruma crates.
 
 #![warn(missing_docs, missing_debug_implementations)]
+#![cfg_attr(docsrs, feature(doc_cfg))]
 
 pub mod authentication;
 pub mod directory;

ruma-common/src/push/predefined.rs

@@ -162,6 +162,7 @@ impl ConditionalPushRule {
     /// Matches emoji reactions to a message
     /// MSC2677: Annotations and Reactions
     #[cfg(feature = "unstable-pre-spec")]
+    #[cfg_attr(docsrs, doc(cfg(feature = "unstable-pre-spec")))]
     pub fn reaction() -> Self {
         Self {
             actions: vec![DontNotify],

ruma-events/src/enums.rs

@@ -37,20 +37,28 @@ event_enum! {
         "m.call.hangup",
         "m.call.candidates",
         #[cfg(feature = "unstable-pre-spec")]
+        #[cfg_attr(docsrs, doc(cfg(feature = "unstable-pre-spec")))]
         "m.key.verification.ready",
         #[cfg(feature = "unstable-pre-spec")]
+        #[cfg_attr(docsrs, doc(cfg(feature = "unstable-pre-spec")))]
         "m.key.verification.start",
         #[cfg(feature = "unstable-pre-spec")]
+        #[cfg_attr(docsrs, doc(cfg(feature = "unstable-pre-spec")))]
         "m.key.verification.cancel",
         #[cfg(feature = "unstable-pre-spec")]
+        #[cfg_attr(docsrs, doc(cfg(feature = "unstable-pre-spec")))]
         "m.key.verification.accept",
         #[cfg(feature = "unstable-pre-spec")]
+        #[cfg_attr(docsrs, doc(cfg(feature = "unstable-pre-spec")))]
         "m.key.verification.key",
         #[cfg(feature = "unstable-pre-spec")]
+        #[cfg_attr(docsrs, doc(cfg(feature = "unstable-pre-spec")))]
         "m.key.verification.mac",
         #[cfg(feature = "unstable-pre-spec")]
+        #[cfg_attr(docsrs, doc(cfg(feature = "unstable-pre-spec")))]
         "m.key.verification.done",
         #[cfg(feature = "unstable-pre-spec")]
+        #[cfg_attr(docsrs, doc(cfg(feature = "unstable-pre-spec")))]
         "m.reaction",
         "m.room.encrypted",
         "m.room.message",

ruma-events/src/key/verification.rs

@@ -20,10 +20,12 @@ use crate::room::relationships::{Reference, RelatesToJsonRepr, RelationJsonRepr}
 pub mod accept;
 pub mod cancel;
 #[cfg(feature = "unstable-pre-spec")]
+#[cfg_attr(docsrs, doc(cfg(feature = "unstable-pre-spec")))]
 pub mod done;
 pub mod key;
 pub mod mac;
 #[cfg(feature = "unstable-pre-spec")]
+#[cfg_attr(docsrs, doc(cfg(feature = "unstable-pre-spec")))]
 pub mod ready;
 pub mod request;
 pub mod start;
@@ -85,6 +87,7 @@ pub enum ShortAuthenticationString {
 #[derive(Clone, Debug, Deserialize, Serialize)]
 #[serde(try_from = "RelatesToJsonRepr", into = "RelatesToJsonRepr")]
 #[cfg(feature = "unstable-pre-spec")]
+#[cfg_attr(docsrs, doc(cfg(feature = "unstable-pre-spec")))]
 pub struct Relation {
     /// The event that is being referenced.
     pub event_id: EventId,

ruma-events/src/key/verification/accept.rs

@@ -18,6 +18,7 @@ use crate::MessageEvent;
 
 /// Accepts a previously sent *m.key.verification.start* message.
 #[cfg(feature = "unstable-pre-spec")]
+#[cfg_attr(docsrs, doc(cfg(feature = "unstable-pre-spec")))]
 pub type AcceptEvent = MessageEvent<AcceptEventContent>;
 
 /// The payload for a to-device `AcceptEvent`.
@@ -39,6 +40,7 @@ pub struct AcceptToDeviceEventContent {
 #[derive(Clone, Debug, Deserialize, Serialize, MessageEventContent)]
 #[ruma_event(type = "m.key.verification.accept")]
 #[cfg(feature = "unstable-pre-spec")]
+#[cfg_attr(docsrs, doc(cfg(feature = "unstable-pre-spec")))]
 pub struct AcceptEventContent {
     /// The method specific content.
     #[serde(flatten)]

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

@@ -13,6 +13,7 @@ use crate::MessageEvent;
 
 /// Cancels a key verification process/request.
 #[cfg(feature = "unstable-pre-spec")]
+#[cfg_attr(docsrs, doc(cfg(feature = "unstable-pre-spec")))]
 pub type CancelEvent = MessageEvent<CancelEventContent>;
 
 /// The payload for a to-device `CancelEvent`.
@@ -35,6 +36,7 @@ pub struct CancelToDeviceEventContent {
 #[derive(Clone, Debug, Deserialize, Serialize, MessageEventContent)]
 #[ruma_event(type = "m.key.verification.cancel")]
 #[cfg(feature = "unstable-pre-spec")]
+#[cfg_attr(docsrs, doc(cfg(feature = "unstable-pre-spec")))]
 pub struct CancelEventContent {
     /// A human readable description of the `code`.
     ///

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

@@ -12,6 +12,7 @@ use crate::MessageEvent;
 
 /// Sends the ephemeral public key for a device to the partner device.
 #[cfg(feature = "unstable-pre-spec")]
+#[cfg_attr(docsrs, doc(cfg(feature = "unstable-pre-spec")))]
 pub type KeyEvent = MessageEvent<KeyEventContent>;
 
 /// The payload for a to-device `KeyEvent`.
@@ -31,6 +32,7 @@ pub struct KeyToDeviceEventContent {
 #[derive(Clone, Debug, Deserialize, Serialize, MessageEventContent)]
 #[ruma_event(type = "m.key.verification.key")]
 #[cfg(feature = "unstable-pre-spec")]
+#[cfg_attr(docsrs, doc(cfg(feature = "unstable-pre-spec")))]
 pub struct KeyEventContent {
     /// The device's ephemeral public key, encoded as unpadded Base64.
     pub key: String,

ruma-events/src/key/verification/mac.rs

@@ -14,6 +14,7 @@ use crate::MessageEvent;
 
 /// Sends the MAC of a device's key to the partner device.
 #[cfg(feature = "unstable-pre-spec")]
+#[cfg_attr(docsrs, doc(cfg(feature = "unstable-pre-spec")))]
 pub type MacEvent = MessageEvent<MacEventContent>;
 
 /// The payload for a to-device `MacEvent`.
@@ -39,6 +40,7 @@ pub struct MacToDeviceEventContent {
 #[derive(Clone, Debug, Deserialize, Serialize, MessageEventContent)]
 #[ruma_event(type = "m.key.verification.mac")]
 #[cfg(feature = "unstable-pre-spec")]
+#[cfg_attr(docsrs, doc(cfg(feature = "unstable-pre-spec")))]
 pub struct MacEventContent {
     /// A map of the key ID to the MAC of the key, using the algorithm in the verification process.
     ///

ruma-events/src/key/verification/start.rs

@@ -20,6 +20,7 @@ use crate::MessageEvent;
 
 /// Begins an SAS key verification process.
 #[cfg(feature = "unstable-pre-spec")]
+#[cfg_attr(docsrs, doc(cfg(feature = "unstable-pre-spec")))]
 pub type StartEvent = MessageEvent<StartEventContent>;
 
 /// The payload of a to-device *m.key.verification.start* event.
@@ -45,6 +46,7 @@ pub struct StartToDeviceEventContent {
 #[derive(Clone, Debug, Deserialize, Serialize, MessageEventContent)]
 #[ruma_event(type = "m.key.verification.start")]
 #[cfg(feature = "unstable-pre-spec")]
+#[cfg_attr(docsrs, doc(cfg(feature = "unstable-pre-spec")))]
 pub struct StartEventContent {
     /// The device ID which is initiating the process.
     pub from_device: DeviceIdBox,

ruma-events/src/lib.rs

@@ -173,9 +173,11 @@ pub mod policy;
 pub mod presence;
 pub mod push_rules;
 #[cfg(feature = "unstable-pre-spec")]
+#[cfg_attr(docsrs, doc(cfg(feature = "unstable-pre-spec")))]
 pub mod reaction;
 pub mod receipt;
 #[cfg(feature = "unstable-pre-spec")]
+#[cfg_attr(docsrs, doc(cfg(feature = "unstable-pre-spec")))]
 pub mod relation;
 pub mod room;
 pub mod room_key;
@@ -185,6 +187,7 @@ pub mod tag;
 pub mod typing;
 
 #[cfg(feature = "unstable-pre-spec")]
+#[cfg_attr(docsrs, doc(cfg(feature = "unstable-pre-spec")))]
 pub use self::relation::Relations;
 pub use self::{
     enums::{
@@ -226,6 +229,7 @@ pub struct Unsigned {
 
     /// Server-compiled information from other events relating to this event.
     #[cfg(feature = "unstable-pre-spec")]
+    #[cfg_attr(docsrs, doc(cfg(feature = "unstable-pre-spec")))]
     #[serde(rename = "m.relations", skip_serializing_if = "Option::is_none")]
     pub relations: Option<Relations>,
 }

ruma-events/src/pdu.rs

@@ -40,6 +40,7 @@ pub struct RoomV1Pdu {
     pub sender: UserId,
 
     #[cfg(not(feature = "unstable-pre-spec"))]
+    #[cfg_attr(docsrs, doc(cfg(not(feature = "unstable-pre-spec"))))]
     /// The `server_name` of the homeserver that created this event.
     pub origin: String,
 
@@ -99,6 +100,7 @@ pub struct RoomV3Pdu {
     pub sender: UserId,
 
     #[cfg(not(feature = "unstable-pre-spec"))]
+    #[cfg_attr(docsrs, doc(cfg(not(feature = "unstable-pre-spec"))))]
     /// The `server_name` of the homeserver that created this event.
     pub origin: String,
 

ruma-events/src/room.rs

@@ -65,6 +65,7 @@ pub struct ImageInfo {
     /// This uses the unstable prefix in
     /// [MSC2448](https://github.com/matrix-org/matrix-doc/pull/2448).
     #[cfg(feature = "unstable-pre-spec")]
+    #[cfg_attr(docsrs, doc(cfg(feature = "unstable-pre-spec")))]
     #[serde(rename = "xyz.amorgan.blurhash")]
     #[serde(skip_serializing_if = "Option::is_none")]
     pub blurhash: Option<String>,

ruma-events/src/room/avatar.rs

@@ -24,22 +24,30 @@ pub struct AvatarEventContent {
     pub info: Option<Box<ImageInfo>>,
 
     /// URL of the avatar image.
+    ///
+    /// With the `unstable-pre-spec` feature, this field is optional.
     #[cfg(not(feature = "unstable-pre-spec"))]
     pub url: MxcUri,
 
     /// URL of the avatar image.
+    ///
+    /// Without the `unstable-pre-spec` feature, this field is not optional.
     #[cfg(feature = "unstable-pre-spec")]
     pub url: Option<MxcUri>,
 }
 
 impl AvatarEventContent {
     /// Create an `AvatarEventContent` from the given image URL.
+    ///
+    /// With the `unstable-pre-spec` feature, this method takes no parameters.
     #[cfg(not(feature = "unstable-pre-spec"))]
     pub fn new(url: MxcUri) -> Self {
         Self { info: None, url }
     }
 
     /// Create an empty `AvatarEventContent`.
+    ///
+    /// With the `unstable-pre-spec` feature, this method takes an `MxcUri`.
     #[cfg(feature = "unstable-pre-spec")]
     pub fn new() -> Self {
         Self::default()
@@ -78,6 +86,7 @@ pub struct ImageInfo {
     /// This uses the unstable prefix in
     /// [MSC2448](https://github.com/matrix-org/matrix-doc/pull/2448).
     #[cfg(feature = "unstable-pre-spec")]
+    #[cfg_attr(docsrs, doc(cfg(feature = "unstable-pre-spec")))]
     #[serde(rename = "xyz.amorgan.blurhash")]
     #[serde(skip_serializing_if = "Option::is_none")]
     pub blurhash: Option<String>,

ruma-events/src/room/message.rs

@@ -50,6 +50,7 @@ pub struct MessageEventContent {
     ///
     /// This should only be set if `relates_to` is `Some(Relation::Replacement(_))`.
     #[cfg(feature = "unstable-pre-spec")]
+    #[cfg_attr(docsrs, doc(cfg(feature = "unstable-pre-spec")))]
     #[serde(rename = "m.new_content", skip_serializing_if = "Option::is_none")]
     pub new_content: Option<Box<MessageEventContent>>,
 }
@@ -120,6 +121,7 @@ pub enum MessageType {
 
     /// A request to initiate a key verification.
     #[cfg(feature = "unstable-pre-spec")]
+    #[cfg_attr(docsrs, doc(cfg(feature = "unstable-pre-spec")))]
     VerificationRequest(KeyVerificationRequestEventContent),
 
     /// A custom message.
@@ -214,14 +216,17 @@ impl From<MessageType> for MessageEventContent {
 pub enum Relation {
     /// A reference to another event.
     #[cfg(feature = "unstable-pre-spec")]
+    #[cfg_attr(docsrs, doc(cfg(feature = "unstable-pre-spec")))]
     Reference(Reference),
 
     /// An annotation to an event.
     #[cfg(feature = "unstable-pre-spec")]
+    #[cfg_attr(docsrs, doc(cfg(feature = "unstable-pre-spec")))]
     Annotation(Annotation),
 
     /// An event that replaces another event.
     #[cfg(feature = "unstable-pre-spec")]
+    #[cfg_attr(docsrs, doc(cfg(feature = "unstable-pre-spec")))]
     Replacement(Replacement),
 
     /// An `m.in_reply_to` relation indicating that the event is a reply to
@@ -643,6 +648,7 @@ pub struct VideoInfo {
     /// This uses the unstable prefix in
     /// [MSC2448](https://github.com/matrix-org/matrix-doc/pull/2448).
     #[cfg(feature = "unstable-pre-spec")]
+    #[cfg_attr(docsrs, doc(cfg(feature = "unstable-pre-spec")))]
     #[serde(rename = "xyz.amorgan.blurhash")]
     #[serde(skip_serializing_if = "Option::is_none")]
     pub blurhash: Option<String>,
@@ -651,6 +657,7 @@ pub struct VideoInfo {
 /// The payload for a key verification request message.
 #[derive(Clone, Debug, Deserialize, Serialize)]
 #[cfg(feature = "unstable-pre-spec")]
+#[cfg_attr(docsrs, doc(cfg(feature = "unstable-pre-spec")))]
 #[serde(tag = "msgtype", rename = "m.key.verification.request")]
 pub struct KeyVerificationRequestEventContent {
     /// A fallback message to alert users that their client does not support the key verification

ruma-events/src/room/relationships.rs

@@ -60,6 +60,7 @@ pub struct InReplyTo {
 /// A reference to another event.
 #[derive(Clone, Debug, Deserialize, Serialize)]
 #[cfg(feature = "unstable-pre-spec")]
+#[cfg_attr(docsrs, doc(cfg(feature = "unstable-pre-spec")))]
 pub struct Reference {
     /// The event we are referencing.
     pub event_id: EventId,
@@ -78,6 +79,7 @@ pub struct Annotation {
 /// An event replacing another event.
 #[derive(Clone, Debug, Deserialize, Serialize)]
 #[cfg(feature = "unstable-pre-spec")]
+#[cfg_attr(docsrs, doc(cfg(feature = "unstable-pre-spec")))]
 pub struct Replacement {
     /// The event this event is replacing.
     pub event_id: EventId,

ruma-federation-api/src/membership/create_join_event.rs

@@ -12,6 +12,7 @@ use serde::{Deserialize, Serialize};
 #[cfg_attr(not(feature = "unstable-exhaustive-types"), non_exhaustive)]
 pub struct RoomState {
     #[cfg(not(feature = "unstable-pre-spec"))]
+    #[cfg_attr(docsrs, doc(cfg(not(feature = "unstable-pre-spec"))))]
     /// The resident server's DNS name.
     pub origin: String,
 
@@ -33,12 +34,17 @@ impl Default for RoomState {
 impl RoomState {
     #[cfg(not(feature = "unstable-pre-spec"))]
     /// Creates an empty `RoomState` with the given `origin`.
+    ///
+    /// With the `unstable-pre-spec` feature, this method doesn't take any parameters.
     pub fn new(origin: String) -> Self {
         Self { origin, auth_chain: Vec::new(), state: Vec::new() }
     }
 
     #[cfg(feature = "unstable-pre-spec")]
     /// Creates an empty `RoomState` with the given `origin`.
+    ///
+    /// Without the `unstable-pre-spec` feature, this method takes a parameter for the origin
+    /// server.
     pub fn new() -> Self {
         Self { auth_chain: Vec::new(), state: Vec::new() }
     }