From 19e849a82ade7af59570ab51f154d4d875d0a17a Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?K=C3=A9vin=20Commaille?= <76261501+zecakeh@users.noreply.github.com> Date: Mon, 12 Apr 2021 11:31:01 +0200 Subject: [PATCH] docs: Document uses of the unstable-pre-spec feature flag --- ruma-client-api/src/lib.rs | 1 + ruma-client-api/src/r0/backup.rs | 1 + ruma-client-api/src/r0/keys.rs | 2 ++ ruma-client-api/src/r0/keys/get_keys.rs | 3 +++ ruma-client-api/src/r0/media/create_content.rs | 1 + ruma-common/src/lib.rs | 1 + ruma-common/src/push/predefined.rs | 1 + ruma-events/src/enums.rs | 8 ++++++++ ruma-events/src/key/verification.rs | 3 +++ ruma-events/src/key/verification/accept.rs | 2 ++ ruma-events/src/key/verification/cancel.rs | 2 ++ ruma-events/src/key/verification/key.rs | 2 ++ ruma-events/src/key/verification/mac.rs | 2 ++ ruma-events/src/key/verification/start.rs | 2 ++ ruma-events/src/lib.rs | 4 ++++ ruma-events/src/pdu.rs | 2 ++ ruma-events/src/room.rs | 1 + ruma-events/src/room/avatar.rs | 9 +++++++++ ruma-events/src/room/message.rs | 7 +++++++ ruma-events/src/room/relationships.rs | 2 ++ ruma-federation-api/src/membership/create_join_event.rs | 6 ++++++ 21 files changed, 62 insertions(+) diff --git a/ruma-client-api/src/lib.rs b/ruma-client-api/src/lib.rs index 92faef23..f4538dc1 100644 --- a/ruma-client-api/src/lib.rs +++ b/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; diff --git a/ruma-client-api/src/r0/backup.rs b/ruma-client-api/src/r0/backup.rs index ea527a84..4ec3fee2 100644 --- a/ruma-client-api/src/r0/backup.rs +++ b/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; diff --git a/ruma-client-api/src/r0/keys.rs b/ruma-client-api/src/r0/keys.rs index 3e7e3457..da548af4 100644 --- a/ruma-client-api/src/r0/keys.rs +++ b/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. diff --git a/ruma-client-api/src/r0/keys/get_keys.rs b/ruma-client-api/src/r0/keys/get_keys.rs index 64165cf8..f35b6b63 100644 --- a/ruma-client-api/src/r0/keys/get_keys.rs +++ b/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, /// 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, /// 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, } diff --git a/ruma-client-api/src/r0/media/create_content.rs b/ruma-client-api/src/r0/media/create_content.rs index 3acddcac..0013968d 100644 --- a/ruma-client-api/src/r0/media/create_content.rs +++ b/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, diff --git a/ruma-common/src/lib.rs b/ruma-common/src/lib.rs index b04a6625..e9e14c16 100644 --- a/ruma-common/src/lib.rs +++ b/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; diff --git a/ruma-common/src/push/predefined.rs b/ruma-common/src/push/predefined.rs index 37a74709..6fde1883 100644 --- a/ruma-common/src/push/predefined.rs +++ b/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], diff --git a/ruma-events/src/enums.rs b/ruma-events/src/enums.rs index 4034289c..406d9ba2 100644 --- a/ruma-events/src/enums.rs +++ b/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", diff --git a/ruma-events/src/key/verification.rs b/ruma-events/src/key/verification.rs index 6a83b43a..9e2c12d9 100644 --- a/ruma-events/src/key/verification.rs +++ b/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, diff --git a/ruma-events/src/key/verification/accept.rs b/ruma-events/src/key/verification/accept.rs index 64f930dc..ff73b8a6 100644 --- a/ruma-events/src/key/verification/accept.rs +++ b/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; /// 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)] diff --git a/ruma-events/src/key/verification/cancel.rs b/ruma-events/src/key/verification/cancel.rs index 14fa2931..d374275f 100644 --- a/ruma-events/src/key/verification/cancel.rs +++ b/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; /// 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`. /// diff --git a/ruma-events/src/key/verification/key.rs b/ruma-events/src/key/verification/key.rs index 7cda74cf..e132e914 100644 --- a/ruma-events/src/key/verification/key.rs +++ b/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; /// 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, diff --git a/ruma-events/src/key/verification/mac.rs b/ruma-events/src/key/verification/mac.rs index bf2e5560..a838b7c9 100644 --- a/ruma-events/src/key/verification/mac.rs +++ b/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; /// 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. /// diff --git a/ruma-events/src/key/verification/start.rs b/ruma-events/src/key/verification/start.rs index fab7b155..b4644168 100644 --- a/ruma-events/src/key/verification/start.rs +++ b/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; /// 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, diff --git a/ruma-events/src/lib.rs b/ruma-events/src/lib.rs index 7c8d323e..bd858bf8 100644 --- a/ruma-events/src/lib.rs +++ b/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, } diff --git a/ruma-events/src/pdu.rs b/ruma-events/src/pdu.rs index 900e9bb0..d24e7c91 100644 --- a/ruma-events/src/pdu.rs +++ b/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, diff --git a/ruma-events/src/room.rs b/ruma-events/src/room.rs index 10ea787c..29de2b8d 100644 --- a/ruma-events/src/room.rs +++ b/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, diff --git a/ruma-events/src/room/avatar.rs b/ruma-events/src/room/avatar.rs index 93a220e3..16c911e5 100644 --- a/ruma-events/src/room/avatar.rs +++ b/ruma-events/src/room/avatar.rs @@ -24,22 +24,30 @@ pub struct AvatarEventContent { pub info: Option>, /// 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, } 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, diff --git a/ruma-events/src/room/message.rs b/ruma-events/src/room/message.rs index bc648412..6c479237 100644 --- a/ruma-events/src/room/message.rs +++ b/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>, } @@ -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 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, @@ -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 diff --git a/ruma-events/src/room/relationships.rs b/ruma-events/src/room/relationships.rs index 050e774b..8cdc5654 100644 --- a/ruma-events/src/room/relationships.rs +++ b/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, diff --git a/ruma-federation-api/src/membership/create_join_event.rs b/ruma-federation-api/src/membership/create_join_event.rs index e66e211a..21443afb 100644 --- a/ruma-federation-api/src/membership/create_join_event.rs +++ b/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() } }