state_store: clean up and add examples to docs

design.md

@@ -19,7 +19,7 @@ In addition to Http, the `AsyncClient` passes along methods from the `BaseClient
   - more?
 
 #### Crypto State Machine
-Given a Matrix response the crypto machine will update it's internal state, along with encryption information this means keeping track of when to encrypt. It knows when encryption needs to happen based on signals from the `BaseClient`. The crypto state machine is given responses that relate to encryption and can create encrypted request bodies for encryption-related requests. Basically it tells the `BaseClient` to send to-device messages out, and the `BaseClient` is responsible for notifying the crypto state machine when it sent the message so crypto can update state.
+Given a Matrix response the crypto machine will update its own internal state, along with encryption information. `BaseClient` and the crypto machine together keep track of when to encrypt. It knows when encryption needs to happen based on signals from the `BaseClient`. The crypto state machine is given responses that relate to encryption and can create encrypted request bodies for encryption-related requests. Basically it tells the `BaseClient` to send to-device messages out, and the `BaseClient` is responsible for notifying the crypto state machine when it sent the message so crypto can update state.
 
 #### Client State/Room and RoomMember
 The `BaseClient` is responsible for keeping state in sync through the `IncomingResponse`s of `AsyncClient` or querying the `StateStore`. By processing and then delegating incoming `RoomEvent`s, `StateEvent`s, `PresenceEvent`, `IncomingAccountData` and `EphemeralEvent`s to the correct `Room` in the base clients `HashMap<RoomId, Room>` or further to `Room`'s `RoomMember` via the members `HashMap<UserId, RoomMember>`. The `BaseClient` is also responsible for emitting the incoming events to the `EventEmitter` trait.
@@ -89,12 +89,12 @@ pub struct RoomMember {
 #### State Store
 The `BaseClient` also has access to a `dyn StateStore` this is an abstraction around a "database" to keep the client state without requesting a full sync from the server on startup. A default implementation that serializes/deserializes JSON to files in a specified directory can be used. The user can also implement `StateStore` to fit any storage solution they choose. The base client handles the storage automatically. There "may be/are TODO" ways for the user to interact directly. The room event handling methods signal if the state was modified; if so, we check if some room state file needs to be overwritten.
   - open
-  - load client/room or rooms
+  - load client/rooms
   - store client/room
   - update ??
 
 The state store will restore our client state in the `BaseClient` and client authors can just get the latest state that they want to present from the client object. No need to ask the state store for it, this may change if custom setups request this. `StateStore`'s main purpose is to provide load/store functionality and, internally to the crate, update the `BaseClient`.
 
 #### Event Emitter
-The consumer of this crate can implement the `EventEmitter` trait for full control over how incoming events are handled by their client. If that isn't enough it is possible to receive every incoming response with the `AsyncClient::sync_forever` callback.
+The consumer of this crate can implement the `EventEmitter` trait for full control over how incoming events are handled by their client. If that isn't enough, it is possible to receive every incoming response with the `AsyncClient::sync_forever` callback.
   - list the methods for `EventEmitter`?

src/async_client.rs

@@ -91,13 +91,13 @@ impl std::fmt::Debug for AsyncClient {
 ///     .unwrap()
 ///     .disable_ssl_verification();
 /// ```
-/// add the default `JsonStore` to the `AsyncClient`
+/// An example of adding a default `JsonStore` to the `AsyncClient`.
 /// ```no_run
 ///  # use matrix_sdk::{AsyncClientConfig, JsonStore};
 ///
 /// let store = JsonStore::open("path/to/json").unwrap();
 /// let client_config = AsyncClientConfig::new()
-///     . state_store(Box::new(store));
+///     .state_store(Box::new(store));
 /// ```
 pub struct AsyncClientConfig {
     proxy: Option<reqwest::Proxy>,
@@ -349,8 +349,23 @@ impl AsyncClient {
     /// Returns true when a successful `StateStore` sync has completed.
     /// # Examples
     ///
-    /// ```
-    /// // TODO
+    /// ```no_run
+    /// use matrix_sdk::{AsyncClient, AsyncClientConfig, JsonStore, RoomBuilder};
+    /// # use matrix_sdk::api::r0::room::Visibility;
+    /// # use url::Url;
+    ///
+    /// # let homeserver = Url::parse("http://example.com").unwrap();
+    /// let store = JsonStore::open("path/to/store").unwrap();
+    /// let config = AsyncClientConfig::new().state_store(Box::new(store));
+    /// let mut cli = AsyncClient::new(homeserver, None).unwrap();
+    /// # use futures::executor::block_on;
+    /// # block_on(async {
+    /// let _ = cli.login("name", "password", None, None).await.unwrap();
+    /// // returns true when a state store sync is successful
+    /// assert!(cli.sync_with_state_store().await.unwrap());
+    /// // now state is restored without a request to the server
+    /// assert_eq!(vec!["room".to_string(), "names".to_string()], cli.get_room_names().await)
+    /// # });
     /// ```
     pub async fn sync_with_state_store(&self) -> Result<bool> {
         self.base_client.write().await.sync_with_state_store().await

src/session.rs

@@ -16,9 +16,8 @@
 //! User sessions.
 
 use ruma_identifiers::UserId;
-use serde::{Deserialize, Serialize};
 /// A user session, containing an access token and information about the associated user account.
-#[derive(Clone, Debug, Eq, Hash, PartialEq, Serialize, Deserialize)]
+#[derive(Clone, Debug, Eq, Hash, PartialEq)]
 pub struct Session {
     /// The access token used for this session.
     pub access_token: String,