[py] Update timeouts.py docstrings (#12523)

* [py] Update docstrings in timeouts.py

* [py] Fix linting

* [py] Implement PR feedback; additional updates to conform more to PEP 257

* [py] Specify that timeouts are in seconds

Author: palmermbandy

py/selenium/webdriver/common/timeouts.py

@@ -15,7 +15,6 @@
 # specific language governing permissions and limitations
 # under the License.
 
-
 from typing import TYPE_CHECKING
 
 if TYPE_CHECKING:
@@ -38,13 +37,13 @@ class JSONTimeouts(TypedDict, total=False):
 
 
 class _TimeoutsDescriptor:
-    """TimeoutsDescriptor which gets and sets value of below attributes:
+    """Get or set the value of the attributes listed below.
 
-    _implicit _timeout
+    _implicit_wait
     _page_load
     _script
 
-    This does not set the value on the remote end
+    This does not set the value on the remote end.
     """
 
     def __init__(self, name):
@@ -60,40 +59,46 @@ def __set__(self, obj, value) -> None:
 
 class Timeouts:
     def __init__(self, implicit_wait: float = 0, page_load: float = 0, script: float = 0) -> None:
-        """Create a new Timeout object.
+        """Create a new Timeouts object.
+
+        This implements https://w3c.github.io/webdriver/#timeouts.
 
         :Args:
-         - implicit_wait - Either an int or a float. The number passed in needs to how many
-            seconds the driver will wait.
-         - page_load - Either an int or a float. The number passed in needs to how many
-            seconds the driver will wait.
-         - script - Either an int or a float. The number passed in needs to how many
-            seconds the driver will wait.
+         - implicit_wait - Either an int or a float. Set how many
+            seconds to wait when searching for elements before
+            throwing an error.
+         - page_load - Either an int or a float. Set how many seconds
+            to wait for a page load to complete before throwing
+            an error.
+         - script - Either an int or a float. Set how many seconds to
+            wait for an asynchronous script to finish execution
+            before throwing an error.
         """
+
         self.implicit_wait = implicit_wait
         self.page_load = page_load
         self.script = script
 
     # Creating descriptor objects
     implicit_wait = _TimeoutsDescriptor("_implicit_wait")
-    """Sets and Gets the value of the implicit_timeout:
+    """Get or set how many seconds to wait when searching for elements.
 
     This does not set the value on the remote end.
 
     Usage
     -----
     - Get
-        - `self.implicit_timeout`
+        - `self.implicit_wait`
     - Set
-        - `self.implicit_timeout` = `value`
+        - `self.implicit_wait` = `value`
 
     Parameters
     ----------
     `value`: `float`
     """
 
     page_load = _TimeoutsDescriptor("_page_load")
-    """Sets and Gets the value of page load wait:
+    """Get or set how many seconds to wait for the page to load.
 
     This does not set the value on the remote end.
 
@@ -110,7 +115,7 @@ def __init__(self, implicit_wait: float = 0, page_load: float = 0, script: float
     """
 
     script = _TimeoutsDescriptor("_script")
-    """Sets and Gets the value of script wait:
+    """Get or set how many seconds to wait for an asynchronous script to finish execution.
 
     This does not set the value on the remote end.