From c41d3873b63e3cd401c3445c326d342ba119fdb9 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Damir=20Jeli=C4=87?= Date: Mon, 2 Mar 2020 11:31:03 +0100 Subject: [PATCH] rust-sdk: Cleanup the docs and fix the examples up. --- Cargo.toml | 2 +- src/async_client.rs | 75 ++++++++++++++++++++++++++++++++----------- src/base_client.rs | 46 +++++++++++++++----------- src/crypto/machine.rs | 19 ++++++++--- 4 files changed, 98 insertions(+), 44 deletions(-) diff --git a/Cargo.toml b/Cargo.toml index 45aa89a6..c12ef69f 100644 --- a/Cargo.toml +++ b/Cargo.toml @@ -35,6 +35,6 @@ cjson = { version = "0.1.0", optional = true } [dev-dependencies] tokio = { version = "0.2.11", features = ["full"] } -async-std = { version = "1.5.0", features = ["attributes"] } +async-std = { version = "1.5.0", features = ["unstable", "attributes"] } url = "2.1.1" mockito = "0.23.3" diff --git a/src/async_client.rs b/src/async_client.rs index 70f10bd2..ead557d7 100644 --- a/src/async_client.rs +++ b/src/async_client.rs @@ -67,10 +67,9 @@ pub struct AsyncClient { /// # Example /// /// ``` +/// # use matrix_sdk::AsyncClientConfig; /// // To pass all the request through mitmproxy set the proxy and disable SSL /// // verification -/// use matrix_sdk::AsyncClientConfig; -/// /// let client_config = AsyncClientConfig::new() /// .proxy("http://localhost:8080") /// .unwrap() @@ -265,7 +264,17 @@ impl AsyncClient { /// received. /// /// # Examples - /// ```noexecute + /// ``` + /// # use matrix_sdk::events::{ + /// # collections::all::RoomEvent, + /// # room::message::{MessageEvent, MessageEventContent, TextMessageEventContent}, + /// # EventResult, + /// # }; + /// # use matrix_sdk::Room; + /// # use std::sync::{Arc, RwLock}; + /// # use matrix_sdk::AsyncClient; + /// # use url::Url; + /// /// async fn async_cb(room: Arc>, event: Arc>) { /// let room = room.read().unwrap(); /// let event = if let EventResult::Ok(event) = &*event { @@ -287,11 +296,15 @@ impl AsyncClient { /// ); /// } /// } + /// # fn main() -> Result<(), matrix_sdk::Error> { + /// let homeserver = Url::parse("http://localhost:8080")?; /// - /// async fn main(client: AsyncClient) { - /// client.add_event_callback(async_cb); - /// } - ///``` + /// let mut client = AsyncClient::new(homeserver, None)?; + /// + /// client.add_event_callback(async_cb); + /// # Ok(()) + /// # } + /// ``` pub fn add_event_callback( &mut self, mut callback: impl FnMut(Arc>, Arc>) -> C + 'static + Send, @@ -309,9 +322,11 @@ impl AsyncClient { /// /// # Arguments /// - /// `user` - The user that should be logged in to the homeserver. - /// `password` - The password of the user. - /// `device_id` - A unique id that will be associated with this session. If + /// * `user` - The user that should be logged in to the homeserver. + /// + /// * `password` - The password of the user. + /// + /// * `device_id` - A unique id that will be associated with this session. If /// not given the homeserver will create one. Can be an exising /// device_id from a previous login call. Note that this should be done /// only if the client also holds the encryption keys for this devcie. @@ -408,6 +423,7 @@ impl AsyncClient { /// /// * `sync_settings` - Settings for the sync call. Note that those settings /// will be only used for the first sync call. + /// /// * `callback` - A callback that will be called every time a successful /// response has been fetched from the server. /// @@ -417,16 +433,35 @@ impl AsyncClient { /// the interesting events through a mpsc channel to another thread e.g. a /// UI thread. /// - /// ```noexecute + /// ```compile_fail,E0658 + /// # use matrix_sdk::events::{ + /// # collections::all::RoomEvent, + /// # room::message::{MessageEvent, MessageEventContent, TextMessageEventContent}, + /// # EventResult, + /// # }; + /// # use matrix_sdk::Room; + /// # use std::sync::{Arc, RwLock}; + /// # use matrix_sdk::{AsyncClient, SyncSettings}; + /// # use url::Url; + /// # use futures::executor::block_on; + /// # block_on(async { + /// # let homeserver = Url::parse("http://localhost:8080").unwrap(); + /// # let mut client = AsyncClient::new(homeserver, None).unwrap(); + /// + /// use async_std::sync::channel; + /// + /// let (tx, rx) = channel(100); + /// + /// let sync_channel = &tx; + /// let sync_settings = SyncSettings::new() + /// .timeout(30_000) + /// .unwrap(); + /// /// client /// .sync_forever(sync_settings, async move |response| { /// let channel = sync_channel; + /// /// for (room_id, room) in response.rooms.join { - /// for event in room.state.events { - /// if let EventResult::Ok(e) = event { - /// channel.send(e).await; - /// } - /// } /// for event in room.timeline.events { /// if let EventResult::Ok(e) = event { /// channel.send(e).await; @@ -435,6 +470,7 @@ impl AsyncClient { /// } /// }) /// .await; + /// }) /// ``` pub async fn sync_forever( &mut self, @@ -542,12 +578,13 @@ impl AsyncClient { /// Send a room message to the homeserver. /// + /// Returns the parsed response from the server. + /// /// # Arguments /// - /// `room_id` - The id of the room that should receive the message. - /// `data` - The content of the message. + /// * `room_id` - The id of the room that should receive the message. /// - /// Returns the parsed response from the server. + /// * `data` - The content of the message. pub async fn room_send( &mut self, room_id: &str, diff --git a/src/base_client.rs b/src/base_client.rs index cb9d3321..6d69aba2 100644 --- a/src/base_client.rs +++ b/src/base_client.rs @@ -58,9 +58,11 @@ pub struct Room { impl Room { /// Create a new room. + /// /// # Arguments /// /// * `room_id` - The unique id of the room. + /// /// * `own_user_id` - The mxid of our own user. pub fn new(room_id: &str, own_user_id: &str) -> Self { Room { @@ -137,11 +139,12 @@ impl Room { } /// Receive a timeline event for this room and update the room state. - /// # Arguments - /// - /// `event` - The event of the room. /// /// Returns true if the joined member list changed, false otherwise. + /// + /// # Arguments + /// + /// * `event` - The event of the room. pub fn receive_timeline_event(&mut self, event: &RoomEvent) -> bool { match event { RoomEvent::RoomMember(m) => self.handle_membership(m), @@ -150,11 +153,12 @@ impl Room { } /// Receive a state event for this room and update the room state. - /// # Arguments - /// - /// `event` - The event of the room. /// /// Returns true if the joined member list changed, false otherwise. + /// + /// # Arguments + /// + /// * `event` - The event of the room. pub fn receive_state_event(&mut self, event: &StateEvent) -> bool { match event { StateEvent::RoomMember(m) => self.handle_membership(m), @@ -180,9 +184,10 @@ pub struct Client { impl Client { /// Create a new client. + /// /// # Arguments /// - /// `session` - An optional session if the user already has one from a + /// * `session` - An optional session if the user already has one from a /// previous login call. pub fn new(session: Option) -> Self { Client { @@ -198,9 +203,10 @@ impl Client { } /// Receive a login response and update the session of the client. + /// /// # Arguments /// - /// `response` - A successful login response that contains our access token + /// * `response` - A successful login response that contains our access token /// and device id. pub fn receive_login_response(&mut self, response: &api::session::login::Response) { let session = Session { @@ -228,13 +234,14 @@ impl Client { /// Receive a timeline event for a joined room and update the client state. /// - /// # Arguments - /// - /// `room_id` - The unique id of the room the event belongs to. - /// `event` - The event that should be handled by the client. - /// /// Returns true if the membership list of the room changed, false /// otherwise. + /// + /// # Arguments + /// + /// * `room_id` - The unique id of the room the event belongs to. + /// + /// * `event` - The event that should be handled by the client. pub fn receive_joined_timeline_event( &mut self, room_id: &str, @@ -251,13 +258,14 @@ impl Client { /// Receive a state event for a joined room and update the client state. /// - /// # Arguments - /// - /// `room_id` - The unique id of the room the event belongs to. - /// `event` - The event that should be handled by the client. - /// /// Returns true if the membership list of the room changed, false /// otherwise. + /// + /// # Arguments + /// + /// * `room_id` - The unique id of the room the event belongs to. + /// + /// * `event` - The event that should be handled by the client. pub fn receive_joined_state_event(&mut self, room_id: &str, event: &StateEvent) -> bool { let mut room = self.get_or_create_room(room_id).write().unwrap(); room.receive_state_event(event) @@ -267,7 +275,7 @@ impl Client { /// /// # Arguments /// - /// `response` - The response that we received after a successful sync. + /// * `response` - The response that we received after a successful sync. pub fn receive_sync_response(&mut self, response: &api::sync::sync_events::IncomingResponse) { self.sync_token = Some(response.next_batch.clone()); } diff --git a/src/crypto/machine.rs b/src/crypto/machine.rs index a3ebe6d6..4ef9b519 100644 --- a/src/crypto/machine.rs +++ b/src/crypto/machine.rs @@ -80,7 +80,7 @@ impl OlmMachine { /// /// # Arguments /// - /// `response` - The keys upload response of the request that the client + /// * `response` - The keys upload response of the request that the client /// performed. pub async fn receive_keys_upload_response(&mut self, response: &keys::upload_keys::Response) { self.account.shared = true; @@ -186,7 +186,13 @@ impl OlmMachine { Ok(one_time_key_map) } - /// Convert a JSON value to the canonical representation and sign the JSON string. + /// Convert a JSON value to the canonical representation and sign the JSON + /// string. + /// + /// # Arguments + /// + /// * `json` - The value that should be converted into a canonical JSON + /// string. fn sign_json(&self, json: &Value) -> String { let canonical_json = cjson::to_string(json) .unwrap_or_else(|_| panic!(format!("Can't serialize {} to canonical JSON", json))); @@ -198,16 +204,19 @@ impl OlmMachine { /// The object must have a signatures key associated with an object of the /// form `user_id: {key_id: signature}`. /// + /// Returns Ok if the signature was successfully verified, otherwise an + /// SignatureError. + /// /// # Arguments /// /// * `user_id` - The user who signed the JSON object. + /// /// * `device_id` - The device that signed the JSON object. + /// /// * `user_key` - The public ed25519 key which was used to sign the JSON /// object. - /// * `json` - The JSON object that should be verified. /// - /// Returns Ok if the signature was successfully verified, otherwise an - /// SignatureError. + /// * `json` - The JSON object that should be verified. fn verify_json( &self, user_id: &str,