From 11fcf5c42f6a04c61f49618f1ae8201d768fec67 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Damir=20Jeli=C4=87?= <poljar@termina.org.uk>
Date: Thu, 5 Nov 2020 14:33:45 +0100
Subject: [PATCH] rust-sdk: Document the cross signing bootstrap method.

---
 matrix_sdk/src/client.rs | 53 +++++++++++++++++++++++++++++++++++++++-
 1 file changed, 52 insertions(+), 1 deletion(-)

diff --git a/matrix_sdk/src/client.rs b/matrix_sdk/src/client.rs
index 14237e4d..7abfa5df 100644
--- a/matrix_sdk/src/client.rs
+++ b/matrix_sdk/src/client.rs
@@ -1832,7 +1832,58 @@ impl Client {
         }))
     }
 
-    /// TODO
+    /// Create and upload a new cross signing identity.
+    ///
+    /// # Arguments
+    ///
+    /// * `auth_data` - This request requires user interactive auth, the first
+    /// request needs to set this to `None` and will always fail with an
+    /// `UiaaResponse`. The response will contain information for the
+    /// interactive auth and the same request needs to be made but this time
+    /// with some `auth_data` provided.
+    ///
+    /// # Examples
+    /// ```no_run
+    /// # use std::{convert::TryFrom, collections::BTreeMap};
+    /// # use matrix_sdk::{Client, identifiers::UserId};
+    /// # use matrix_sdk::api::r0::uiaa::AuthData;
+    /// # use url::Url;
+    /// # use futures::executor::block_on;
+    /// # use serde_json::json;
+    /// # let user_id = UserId::try_from("@alice:example.org").unwrap();
+    /// # let homeserver = Url::parse("http://example.com").unwrap();
+    /// # let client = Client::new(homeserver).unwrap();
+    /// # block_on(async {
+    ///
+    /// fn auth_data<'a>(user: &UserId, password: &str, session: Option<&'a str>) -> AuthData<'a> {
+    ///     let mut auth_parameters = BTreeMap::new();
+    ///     let identifier = json!({
+    ///         "type": "m.id.user",
+    ///         "user": user,
+    ///     });
+    ///     auth_parameters.insert("identifier".to_owned(), identifier);
+    ///     auth_parameters.insert("password".to_owned(), password.to_owned().into());
+    ///     // This is needed because of https://github.com/matrix-org/synapse/issues/5665
+    ///     auth_parameters.insert("user".to_owned(), user.as_str().into());
+    ///     AuthData::DirectRequest {
+    ///         kind: "m.login.password",
+    ///         auth_parameters,
+    ///         session,
+    ///     }
+    /// }
+    ///
+    /// if let Err(e) = client.bootstrap_cross_signing(None).await {
+    ///     if let Some(response) = e.uiaa_response() {
+    ///         let auth_data = auth_data(&user_id, "wordpass", response.session.as_deref());
+    ///            client
+    ///                .bootstrap_cross_signing(Some(auth_data))
+    ///                .await
+    ///                .expect("Couldn't bootstrap cross signing")
+    ///     } else {
+    ///         panic!("Error durign cross signing bootstrap {:#?}", e);
+    ///     }
+    /// }
+    /// # })
     #[cfg(feature = "encryption")]
     #[cfg_attr(feature = "docs", doc(cfg(encryption)))]
     pub async fn bootstrap_cross_signing(&self, auth_data: Option<AuthData<'_>>) -> Result<()> {