From 66ccc81efcecb6fefc2cb1e340f8fd0c898f00e0 Mon Sep 17 00:00:00 2001
From: Steve Pryde <steve@stevepryde.com>
Date: Mon, 5 Oct 2020 10:36:25 +1030
Subject: [PATCH] Improve docs and add support for specifying ElementPoller
 directly

---
 Cargo.toml   |  4 ++--
 README.md    | 27 ++++++++++++---------------
 src/lib.rs   | 28 ++++++++++++----------------
 src/query.rs | 17 +++++++++++------
 4 files changed, 37 insertions(+), 39 deletions(-)

diff --git a/Cargo.toml b/Cargo.toml
index dae0ac5..b70f70c 100644
--- a/Cargo.toml
+++ b/Cargo.toml
@@ -1,10 +1,10 @@
 [package]
 name = "thirtyfour_query"
-version = "0.4.0"
+version = "0.4.1"
 authors = ["Steve Pryde <steve@stevepryde.com>"]
 edition = "2018"
 license = "MIT OR Apache-2.0"
-description = "Advanced element query interface for thirtyfour crate"
+description = "Advanced element query interface for the thirtyfour crate"
 homepage = "https://github.com/stevepryde/thirtyfour_query"
 repository = "https://github.com/stevepryde/thirtyfour_query"
 documentation = "https://docs.rs/thirtyfour_query"
diff --git a/README.md b/README.md
index 9b6ee09..de48814 100644
--- a/README.md
+++ b/README.md
@@ -3,13 +3,21 @@
 
 Advanced element query interface for the thirtyfour crate.
 
-## Experimental 
+## Usage
+
+First, set the default polling behaviour:
+```rust 
+// Disable implicit timeout in order to use new query interface.
+driver.set_implicit_wait_timeout(Duration::new(0, 0)).await?;
 
-This crate is experimental and expected to have breaking changes often.
+let poller = ElementPoller::TimeoutWithInterval(Duration::new(20, 0), Duration::from_millis(500));
+driver.config_mut().set("ElementPoller", poller)?;
+```
 
-## Usage
+Other ElementPoller options are also available, such as NoWait and NumTriesWithInterval.
+These can be overridden on a per-query basis as needed.
 
-With the new query interface you can do things like:
+Now, using the query interface you can do things like:
 
 ```rust
 let elem_text = 
@@ -30,17 +38,6 @@ and you'll get a Vec instead. This will never return an empty Vec. If either fir
 don't match anything, you'll get `WebDriverError::NoSuchElement` instead. 
 The error message will show the selectors used.
 
-To set up default polling for all elements, do this:
-```rust 
-// Disable implicit timeout in order to use new query interface.
-driver.set_implicit_wait_timeout(Duration::new(0, 0)).await?;
-
-let poller = ElementPoller::Time(Duration::new(20, 0), Duration::from_millis(500));
-driver.config_mut().set("ElementPoller", poller)?;
-```
-
-Other ElementPoller options are also available, such as NoWait and NumTries.
-
 ## LICENSE
 
 This work is dual-licensed under MIT or Apache 2.0.
diff --git a/src/lib.rs b/src/lib.rs
index 39ba030..c1cba78 100644
--- a/src/lib.rs
+++ b/src/lib.rs
@@ -3,14 +3,21 @@
 //!
 //! See examples for more details.
 //!
-//! ## Experimental
+//! ## Usage
 //!
-//! This crate is still experimental and expected to have breaking changes often, however
-//! the basic interface is working.
+//! First, set the default polling behaviour:
+//! ```no_run
+//! // Disable implicit timeout in order to use new query interface.
+//! driver.set_implicit_wait_timeout(Duration::new(0, 0)).await?;
 //!
-//! ## Usage
+//! let poller = ElementPoller::TimeoutWithInterval(Duration::new(20, 0), Duration::from_millis(500));
+//! driver.config_mut().set("ElementPoller", poller)?;
+//! ```
+//!
+//! Other ElementPoller options are also available, such as NoWait and NumTriesWithInterval.
+//! These can be overridden on a per-query basis as needed.
 //!
-//! With the new query interface you can do things like:
+//! Now, using the query interface you can do things like:
 //!
 //! ```no_run
 //! let elem_text =
@@ -31,15 +38,4 @@
 //! don't match anything, you'll get `WebDriverError::NoSuchElement` instead.
 //! The error message will show the selectors used.
 //!
-//! To set up default polling for all elements, do this:
-//! ```no_run
-//! // Disable implicit timeout in order to use new query interface.
-//! driver.set_implicit_wait_timeout(Duration::new(0, 0)).await?;
-//!
-//! let poller = ElementPoller::TimeoutWithInterval(Duration::new(20, 0), Duration::from_millis(500));
-//! driver.config_mut().set("ElementPoller", poller)?;
-//! ```
-//!
-//! Other ElementPoller options are also available, such as NoWait and NumTries.
-
 pub mod query;
diff --git a/src/query.rs b/src/query.rs
index 5533d74..b591e4b 100644
--- a/src/query.rs
+++ b/src/query.rs
@@ -135,19 +135,24 @@ impl<'a> ElementQuery<'a> {
         }
     }
 
+    /// Use the specified ElementPoller for this ElementQuery.
+    /// This will not affect the default ElementPoller used for other queries.
+    pub fn with_poller(mut self, poller: ElementPoller) -> Self {
+        self.poller = poller;
+        self
+    }
+
     /// Force this ElementQuery to wait for the specified timeout, polling once
     /// after each interval. This will override the poller for this
     /// ElementQuery only.
-    pub fn wait(mut self, timeout: Duration, interval: Duration) -> Self {
-        self.poller = ElementPoller::TimeoutWithInterval(timeout, interval);
-        self
+    pub fn wait(self, timeout: Duration, interval: Duration) -> Self {
+        self.with_poller(ElementPoller::TimeoutWithInterval(timeout, interval))
     }
 
     /// Force this ElementQuery to not wait for the specified condition(s).
     /// This will override the poller for this ElementQuery only.
-    pub fn nowait(mut self) -> Self {
-        self.poller = ElementPoller::NoWait;
-        self
+    pub fn nowait(self) -> Self {
+        self.with_poller(ElementPoller::NoWait)
     }
 
     /// Add the specified selector to this ElementQuery. Callers should use