Improve the explanation of waits

rogererens · baijum · commit 09abf56163a5 · 2017-02-21T19:15:18.000+05:30
diff --git a/source/waits.rst b/source/waits.rst
@@ -4,26 +4,26 @@ Waits
 -----
 
 These days most of the web apps are using AJAX techniques.  When a
-page is loaded to browser, the elements within that page may load at
-different time intervals.  This makes locating elements difficult, if
-the element is not present in the DOM, it will raise
-`ElementNotVisibleException` exception.  Using waits, we can solve
-this issue.  Waiting provides some time interval between actions
-performed - mostly locating element or any other operation with the
+page is loaded by the browser, the elements within that page may load at
+different time intervals.  This makes locating elements difficult: if
+an element is not yet present in the DOM, a locate function will raise
+an `ElementNotVisibleException` exception.  Using waits, we can solve
+this issue.  Waiting provides some slack between actions
+performed - mostly locating an element or any other operation with the
 element.
 
 Selenium Webdriver provides two types of waits - implicit & explicit.
-An explicit wait makes WebDriver to wait for a certain condition to
-occur before proceeding further with executions.  An implicit wait
-makes WebDriver to poll the DOM for a certain amount of time when
+An explicit wait makes WebDriver wait for a certain condition to
+occur before proceeding further with execution.  An implicit wait
+makes WebDriver poll the DOM for a certain amount of time when
 trying to locate an element.
 
 
 Explicit Waits
 ~~~~~~~~~~~~~~
 
 An explicit wait is code you define to wait for a certain condition
-to occur before proceeding further in the code.  The worst case of
+to occur before proceeding further in the code.  The extreme case of
 this is time.sleep(), which sets the condition to an exact time period
 to wait.  There are some convenience methods provided that help you
 write code that will wait only as long as required.  WebDriverWait in
@@ -47,17 +47,17 @@ accomplished.
       driver.quit()
 
 
-This waits up to 10 seconds before throwing a TimeoutException or if
-it finds the element will return it in 0 - 10 seconds.  WebDriverWait
+This waits up to 10 seconds before throwing a TimeoutException unless 
+it finds the element to return within 10 seconds.  WebDriverWait
 by default calls the ExpectedCondition every 500 milliseconds until it
 returns successfully.  A successful return is for ExpectedCondition
 type is Boolean return true or not null return value for all other
 ExpectedCondition types.
 
 **Expected Conditions**
 
-There are some common conditions that are frequent when
-automating web browsers.  Listed below are Implementations of
+There are some common conditions that are frequently of use when
+automating web browsers.  Listed below are the names of
 each. Selenium Python binding provides some convienence methods so you
 don't have to code an expected_condition class yourself or create your
 own utility package for them.
@@ -72,7 +72,7 @@ own utility package for them.
 - text_to_be_present_in_element_value
 - frame_to_be_available_and_switch_to_it
 - invisibility_of_element_located
-- element_to_be_clickable - it is Displayed and Enabled.
+- element_to_be_clickable
 - staleness_of
 - element_to_be_selected
 - element_located_to_be_selected
@@ -85,7 +85,7 @@ own utility package for them.
   from selenium.webdriver.support import expected_conditions as EC
 
   wait = WebDriverWait(driver, 10)
-  element = wait.until(EC.element_to_be_clickable((By.ID,'someid')))
+  element = wait.until(EC.element_to_be_clickable((By.ID, 'someid')))
 
 The expected_conditions module contains a set of predefined conditions
 to use with WebDriverWait.
@@ -94,10 +94,10 @@ to use with WebDriverWait.
 Implicit Waits
 ~~~~~~~~~~~~~~
 
-An implicit wait is to tell WebDriver to poll the DOM for a certain
-amount of time when trying to find an element or elements if they are
+An implicit wait tells WebDriver to poll the DOM for a certain
+amount of time when trying to find any element (or elements)
 not immediately available.  The default setting is 0.  Once set, the
-implicit wait is set for the life of the WebDriver object instance.
+implicit wait is set for the life of the WebDriver object.
 
 ::
 
