diff --git a/matrix_sdk/src/client.rs b/matrix_sdk/src/client.rs
index 7e0d7428..25b6acee 100644
--- a/matrix_sdk/src/client.rs
+++ b/matrix_sdk/src/client.rs
@@ -414,6 +414,15 @@ impl Client {
 
     /// Login to the server.
     ///
+    /// This can be used for the first login as well as for subsequent logins,
+    /// note that if the device id isn't provided a new device will be created.
+    ///
+    /// If this isn't the first login a device id should be provided to restore
+    /// the correct stores.
+    ///
+    /// Alternatively the `restore_login()` method can be used to restore a
+    /// logged in client without the password.
+    ///
     /// # Arguments
     ///
     /// * `user` - The user that should be logged in to the homeserver.
@@ -451,6 +460,12 @@ impl Client {
 
     /// Restore a previously logged in session.
     ///
+    /// This can be used to restore the client to a logged in state, loading all
+    /// the stored state and encryption keys.
+    ///
+    /// Alternatively, if the whole session isn't stored the `login()` method
+    /// can be used with a device id.
+    ///
     /// # Arguments
     ///
     /// * `session` - A session that the user already has from a