From 2a5ede9e1aff40aca61cc5824d6d0fb9bc56487f Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Damir=20Jeli=C4=87?= <poljar@termina.org.uk>
Date: Wed, 21 Apr 2021 15:08:36 +0200
Subject: [PATCH] client: Better docs for the get_or_upload_filter() method

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

diff --git a/matrix_sdk/src/client.rs b/matrix_sdk/src/client.rs
index a554f0ba..2c1f6877 100644
--- a/matrix_sdk/src/client.rs
+++ b/matrix_sdk/src/client.rs
@@ -1229,6 +1229,56 @@ impl Client {
     }
 
     /// Get or upload a sync filter.
+    ///
+    /// This method will either get a filter ID from the store or upload the
+    /// filter definition to the homeserver and return the new filter ID.
+    ///
+    /// # Arguments
+    ///
+    /// * `filter_name` - The unique name of the filter, this name will be used
+    /// locally to store and identify the filter ID returned by the server.
+    ///
+    /// * `definition` - The filter definition that should be uploaded to the
+    /// server if no filter ID can be found in the store.
+    ///
+    /// # Examples
+    ///
+    /// ```no_run
+    /// # use matrix_sdk::{
+    /// #    Client, SyncSettings,
+    /// #    api::r0::{
+    /// #        filter::{
+    /// #           FilterDefinition, LazyLoadOptions, RoomEventFilter, RoomFilter,
+    /// #        },
+    /// #        sync::sync_events::Filter,
+    /// #    }
+    /// # };
+    /// # use futures::executor::block_on;
+    /// # use url::Url;
+    /// # let homeserver = Url::parse("http://example.com").unwrap();
+    /// # let client = Client::new(homeserver).unwrap();
+    /// # block_on(async {
+    /// let mut filter = FilterDefinition::default();
+    /// let mut room_filter = RoomFilter::default();
+    /// let mut event_filter = RoomEventFilter::default();
+    ///
+    /// // Let's enable member lazy loading.
+    /// event_filter.lazy_load_options = LazyLoadOptions::Enabled {
+    ///     include_redundant_members: false,
+    /// };
+    /// room_filter.state = event_filter;
+    /// filter.room = room_filter;
+    ///
+    /// let filter_id = client
+    ///     .get_or_upload_filter("sync", filter)
+    ///     .await
+    ///     .unwrap();
+    ///
+    /// let sync_settings = SyncSettings::new()
+    ///     .filter(Filter::FilterId(&filter_id));
+    ///
+    /// let response = client.sync_once(sync_settings).await.unwrap();
+    /// # });
     pub async fn get_or_upload_filter(
         &self,
         filter_name: &str,