From d4de877e09b8802189634a99cc15851c61f45071 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Damir=20Jeli=C4=87?= Date: Thu, 13 Aug 2020 12:17:30 +0200 Subject: [PATCH] base: Fix the docs for our feature flags. --- matrix_sdk_base/Cargo.toml | 6 +++++ matrix_sdk_base/src/client.rs | 36 +++++++++++++++--------------- matrix_sdk_base/src/error.rs | 4 ++-- matrix_sdk_base/src/lib.rs | 4 +++- matrix_sdk_base/src/models/mod.rs | 3 +-- matrix_sdk_base/src/models/room.rs | 6 ++--- 6 files changed, 33 insertions(+), 26 deletions(-) diff --git a/matrix_sdk_base/Cargo.toml b/matrix_sdk_base/Cargo.toml index f7c5a79a..407680b0 100644 --- a/matrix_sdk_base/Cargo.toml +++ b/matrix_sdk_base/Cargo.toml @@ -10,12 +10,18 @@ readme = "README.md" repository = "https://github.com/matrix-org/matrix-rust-sdk" version = "0.1.0" +[package.metadata.docs.rs] +features = ["docs"] +rustdoc-args = ["--cfg", "feature=\"docs\""] + [features] default = ["encryption", "sqlite_cryptostore", "messages"] messages = [] encryption = ["matrix-sdk-crypto"] sqlite_cryptostore = ["matrix-sdk-crypto/sqlite_cryptostore"] +docs = ["encryption", "sqlite_cryptostore", "messages"] + [dependencies] async-trait = "0.1.36" serde = "1.0.115" diff --git a/matrix_sdk_base/src/client.rs b/matrix_sdk_base/src/client.rs index 6334041b..54cbd0fd 100644 --- a/matrix_sdk_base/src/client.rs +++ b/matrix_sdk_base/src/client.rs @@ -1231,7 +1231,7 @@ impl BaseClient { /// Should account or one-time keys be uploaded to the server. #[cfg(feature = "encryption")] - #[cfg_attr(docsrs, doc(cfg(feature = "encryption")))] + #[cfg_attr(feature = "docs", doc(cfg(encryption)))] pub async fn should_upload_keys(&self) -> bool { let olm = self.olm.lock().await; @@ -1250,7 +1250,7 @@ impl BaseClient { /// This should be called every time a new room message wants to be sent out /// since group sessions can expire at any time. #[cfg(feature = "encryption")] - #[cfg_attr(docsrs, doc(cfg(feature = "encryption")))] + #[cfg_attr(feature = "docs", doc(cfg(encryption)))] pub async fn should_share_group_session(&self, room_id: &RoomId) -> bool { let olm = self.olm.lock().await; @@ -1262,7 +1262,7 @@ impl BaseClient { /// Should users be queried for their device keys. #[cfg(feature = "encryption")] - #[cfg_attr(docsrs, doc(cfg(feature = "encryption")))] + #[cfg_attr(feature = "docs", doc(cfg(encryption)))] pub async fn should_query_keys(&self) -> bool { let olm = self.olm.lock().await; @@ -1276,7 +1276,7 @@ impl BaseClient { /// /// Returns an empty error if no keys need to be uploaded. #[cfg(feature = "encryption")] - #[cfg_attr(docsrs, doc(cfg(feature = "encryption")))] + #[cfg_attr(feature = "docs", doc(cfg(encryption)))] pub async fn get_missing_sessions( &self, users: impl Iterator, @@ -1291,7 +1291,7 @@ impl BaseClient { /// Get a to-device request that will share a group session for a room. #[cfg(feature = "encryption")] - #[cfg_attr(docsrs, doc(cfg(feature = "encryption")))] + #[cfg_attr(feature = "docs", doc(cfg(encryption)))] pub async fn share_group_session(&self, room_id: &RoomId) -> Result> { let room = self.get_joined_room(room_id).await.expect("No room found"); let olm = self.olm.lock().await; @@ -1313,7 +1313,7 @@ impl BaseClient { /// Encrypt a message event content. #[cfg(feature = "encryption")] - #[cfg_attr(docsrs, doc(cfg(feature = "encryption")))] + #[cfg_attr(feature = "docs", doc(cfg(encryption)))] pub async fn encrypt( &self, room_id: &RoomId, @@ -1331,7 +1331,7 @@ impl BaseClient { /// /// Returns an empty error if no keys need to be uploaded. #[cfg(feature = "encryption")] - #[cfg_attr(docsrs, doc(cfg(feature = "encryption")))] + #[cfg_attr(feature = "docs", doc(cfg(encryption)))] pub async fn keys_for_upload(&self) -> StdResult { let olm = self.olm.lock().await; @@ -1345,7 +1345,7 @@ impl BaseClient { /// /// Returns an empty error if no keys need to be queried. #[cfg(feature = "encryption")] - #[cfg_attr(docsrs, doc(cfg(feature = "encryption")))] + #[cfg_attr(feature = "docs", doc(cfg(encryption)))] pub async fn users_for_key_query(&self) -> StdResult, ()> { let olm = self.olm.lock().await; @@ -1365,7 +1365,7 @@ impl BaseClient { /// # Panics /// Panics if the client hasn't been logged in. #[cfg(feature = "encryption")] - #[cfg_attr(docsrs, doc(cfg(feature = "encryption")))] + #[cfg_attr(feature = "docs", doc(cfg(encryption)))] pub async fn receive_keys_upload_response(&self, response: &KeysUploadResponse) -> Result<()> { let olm = self.olm.lock().await; @@ -1384,7 +1384,7 @@ impl BaseClient { /// # Panics /// Panics if the client hasn't been logged in. #[cfg(feature = "encryption")] - #[cfg_attr(docsrs, doc(cfg(feature = "encryption")))] + #[cfg_attr(feature = "docs", doc(cfg(encryption)))] pub async fn receive_keys_claim_response(&self, response: &KeysClaimResponse) -> Result<()> { let olm = self.olm.lock().await; @@ -1403,7 +1403,7 @@ impl BaseClient { /// # Panics /// Panics if the client hasn't been logged in. #[cfg(feature = "encryption")] - #[cfg_attr(docsrs, doc(cfg(feature = "encryption")))] + #[cfg_attr(feature = "docs", doc(cfg(encryption)))] pub async fn receive_keys_query_response(&self, response: &KeysQueryResponse) -> Result<()> { let olm = self.olm.lock().await; @@ -1419,7 +1419,7 @@ impl BaseClient { /// Returns true if a session was invalidated, false if there was no session /// to invalidate. #[cfg(feature = "encryption")] - #[cfg_attr(docsrs, doc(cfg(feature = "encryption")))] + #[cfg_attr(feature = "docs", doc(cfg(encryption)))] pub async fn invalidate_group_session(&self, room_id: &RoomId) -> bool { let olm = self.olm.lock().await; @@ -1831,7 +1831,7 @@ impl BaseClient { /// Get the to-device requests that need to be sent out. #[cfg(feature = "encryption")] - #[cfg_attr(docsrs, doc(cfg(feature = "encryption")))] + #[cfg_attr(feature = "docs", doc(cfg(encryption)))] pub async fn outgoing_to_device_requests(&self) -> Vec { self.olm .lock() @@ -1843,7 +1843,7 @@ impl BaseClient { /// Mark an outgoing to-device requests as sent. #[cfg(feature = "encryption")] - #[cfg_attr(docsrs, doc(cfg(feature = "encryption")))] + #[cfg_attr(feature = "docs", doc(cfg(encryption)))] pub async fn mark_to_device_request_as_sent(&self, request_id: &str) { if let Some(olm) = self.olm.lock().await.as_ref() { olm.mark_to_device_request_as_sent(request_id) @@ -1860,7 +1860,7 @@ impl BaseClient { /// to-device verification flows this will be the transaction id of the /// *m.key.verification.start* event. #[cfg(feature = "encryption")] - #[cfg_attr(docsrs, doc(cfg(feature = "encryption")))] + #[cfg_attr(feature = "docs", doc(cfg(encryption)))] pub async fn get_verification(&self, flow_id: &str) -> Option { self.olm .lock() @@ -1878,7 +1878,7 @@ impl BaseClient { /// /// Returns a `Sas` object and a to-device request that needs to be sent out. #[cfg(feature = "encryption")] - #[cfg_attr(docsrs, doc(cfg(feature = "encryption")))] + #[cfg_attr(feature = "docs", doc(cfg(encryption)))] pub async fn start_verification(&self, device: Device) -> Option<(Sas, OwnedToDeviceRequest)> { self.olm .lock() @@ -1916,7 +1916,7 @@ impl BaseClient { /// # }); /// ``` #[cfg(feature = "encryption")] - #[cfg_attr(docsrs, doc(cfg(feature = "encryption")))] + #[cfg_attr(feature = "docs", doc(cfg(encryption)))] pub async fn get_device(&self, user_id: &UserId, device_id: &DeviceId) -> Option { let olm = self.olm.lock().await; olm.as_ref()?.get_device(user_id, device_id).await @@ -1949,7 +1949,7 @@ impl BaseClient { /// # }); /// ``` #[cfg(feature = "encryption")] - #[cfg_attr(docsrs, doc(cfg(feature = "encryption")))] + #[cfg_attr(feature = "docs", doc(cfg(encryption)))] pub async fn get_user_devices( &self, user_id: &UserId, diff --git a/matrix_sdk_base/src/error.rs b/matrix_sdk_base/src/error.rs index c1134593..962e3014 100644 --- a/matrix_sdk_base/src/error.rs +++ b/matrix_sdk_base/src/error.rs @@ -47,13 +47,13 @@ pub enum Error { /// An error occurred during a E2EE operation. #[cfg(feature = "encryption")] - #[cfg_attr(docsrs, doc(cfg(feature = "encryption")))] + #[cfg_attr(feature = "docs", doc(cfg(encryption)))] #[error(transparent)] OlmError(#[from] OlmError), /// An error occurred during a E2EE group operation. #[cfg(feature = "encryption")] - #[cfg_attr(docsrs, doc(cfg(feature = "encryption")))] + #[cfg_attr(feature = "docs", doc(cfg(encryption)))] #[error(transparent)] MegolmError(#[from] MegolmError), } diff --git a/matrix_sdk_base/src/lib.rs b/matrix_sdk_base/src/lib.rs index 666db669..18617146 100644 --- a/matrix_sdk_base/src/lib.rs +++ b/matrix_sdk_base/src/lib.rs @@ -34,6 +34,7 @@ unused_import_braces, unused_qualifications )] +#![cfg_attr(feature = "docs", feature(doc_cfg))] pub use crate::{ error::{Error, Result}, @@ -54,10 +55,11 @@ pub use models::Room; pub use state::{AllRooms, ClientState}; #[cfg(feature = "encryption")] +#[cfg_attr(feature = "docs", doc(cfg(encryption)))] pub use matrix_sdk_crypto::{CryptoStoreError, Device, Sas, TrustState, UserDevices}; #[cfg(feature = "messages")] -#[cfg_attr(docsrs, doc(cfg(feature = "messages")))] +#[cfg_attr(feature = "docs", doc(cfg(messages)))] pub use models::{MessageQueue, PossiblyRedactedExt}; #[cfg(not(target_arch = "wasm32"))] diff --git a/matrix_sdk_base/src/models/mod.rs b/matrix_sdk_base/src/models/mod.rs index bf2eefb0..c9d55af2 100644 --- a/matrix_sdk_base/src/models/mod.rs +++ b/matrix_sdk_base/src/models/mod.rs @@ -1,11 +1,10 @@ #[cfg(feature = "messages")] -#[cfg_attr(docsrs, doc(cfg(feature = "messages")))] mod message; mod room; mod room_member; #[cfg(feature = "messages")] -#[cfg_attr(docsrs, doc(cfg(feature = "messages")))] +#[cfg_attr(feature = "docs", doc(cfg(messages)))] pub use message::{MessageQueue, PossiblyRedactedExt}; pub use room::{Room, RoomName}; pub use room_member::RoomMember; diff --git a/matrix_sdk_base/src/models/room.rs b/matrix_sdk_base/src/models/room.rs index 1e5aedbc..d3476c2f 100644 --- a/matrix_sdk_base/src/models/room.rs +++ b/matrix_sdk_base/src/models/room.rs @@ -172,7 +172,7 @@ pub struct Room { /// This is helpful when using a `StateStore` to avoid multiple requests to /// the server for messages. #[cfg(feature = "messages")] - #[cfg_attr(docsrs, doc(cfg(feature = "messages")))] + #[cfg_attr(feature = "docs", doc(cfg(messages)))] #[serde(with = "super::message::ser_deser")] pub messages: MessageQueue, /// A list of users that are currently typing. @@ -656,7 +656,7 @@ impl Room { /// /// Returns true if `MessageQueue` was added to. #[cfg(feature = "messages")] - #[cfg_attr(docsrs, doc(cfg(feature = "messages")))] + #[cfg_attr(feature = "docs", doc(cfg(messages)))] pub fn handle_message(&mut self, event: &AnySyncMessageEvent) -> bool { self.messages .push(AnyPossiblyRedactedSyncMessageEvent::Regular(event.clone())) @@ -669,7 +669,7 @@ impl Room { /// whole redaction event is added to the `Unsigned` `redacted_because` /// field. #[cfg(feature = "messages")] - #[cfg_attr(docsrs, doc(cfg(feature = "messages")))] + #[cfg_attr(feature = "docs", doc(cfg(messages)))] pub fn handle_redaction(&mut self, redacted_event: &SyncRedactionEvent) -> bool { use crate::{identifiers::RoomVersionId, models::message::PossiblyRedactedExt};