From 42c8c421502b12a9af8e058c7cd9cca8cbcb0eb3 Mon Sep 17 00:00:00 2001
From: Jan Veen <jan.veen@posteo.de>
Date: Fri, 12 Mar 2021 15:45:58 +0100
Subject: [PATCH] crypto: Improve doc of SAS accept settings

Document arguments explicitly.

Adapt to changed implementation.

Provide example call.
---
 matrix_sdk/src/sas.rs                         | 17 ++++++++++++++++-
 matrix_sdk_crypto/src/verification/sas/mod.rs |  7 ++++++-
 2 files changed, 22 insertions(+), 2 deletions(-)

diff --git a/matrix_sdk/src/sas.rs b/matrix_sdk/src/sas.rs
index 2baa10c0..01d548fe 100644
--- a/matrix_sdk/src/sas.rs
+++ b/matrix_sdk/src/sas.rs
@@ -33,7 +33,22 @@ impl Sas {
 
     /// Accept the interactive verification flow with specific settings.
     ///
-    /// Pass `settings` to customizes the accept-request before sending it.
+    /// # Arguments
+    ///
+    /// * `settings` - specific customizations to the verification flow.
+    ///
+    /// # Examples
+    ///
+    /// ```ignore
+    /// use matrix_sdk::Sas;
+    /// use matrix_sdk_base::crypto::AcceptSettings;
+    /// use matrix_sdk::events::key::verification::ShortAuthenticationString;
+    ///
+    /// let only_decimal = AcceptSettings::with_allowed_methods(
+    ///     vec![ShortAuthenticationString::Decimal]
+    /// );
+    /// sas.accept_with_settings(only_decimal);
+    /// ```
     pub async fn accept_with_settings(&self, settings: AcceptSettings) -> Result<()> {
         if let Some(req) = self.inner.accept_with_settings(settings) {
             match req {
diff --git a/matrix_sdk_crypto/src/verification/sas/mod.rs b/matrix_sdk_crypto/src/verification/sas/mod.rs
index 4c0f3abf..12b5f161 100644
--- a/matrix_sdk_crypto/src/verification/sas/mod.rs
+++ b/matrix_sdk_crypto/src/verification/sas/mod.rs
@@ -682,6 +682,7 @@ pub struct AcceptSettings {
 }
 
 impl Default for AcceptSettings {
+    /// All methods are allowed
     fn default() -> Self {
         Self {
             allowed_methods: vec![
@@ -693,7 +694,11 @@ impl Default for AcceptSettings {
 }
 
 impl AcceptSettings {
-    /// Create settings with exactly the specified SAS methods
+    /// Create settings restricting the allowed SAS methods
+    ///
+    /// # Arguments
+    ///
+    /// * `methods` - The methods this client allows at most
     pub fn with_allowed_methods(methods: Vec<ShortAuthenticationString>) -> Self {
         Self {
             allowed_methods: methods,