Refactor docstrings for consistency and clarity across WebDriver and ChromiumOptions classes

Author: iampopovich

py/selenium/webdriver/chrome/webdriver.py

@@ -32,13 +32,14 @@ def __init__(
         service: Optional[Service] = None,
         keep_alive: bool = True,
     ) -> None:
-        """Creates a new instance of the chrome driver. Starts the service and
-        then creates new instance of chrome driver.
+        """Creates a new instance of the chrome driver.
 
-        :Args:
-         - options - this takes an instance of ChromeOptions
-         - service - Service object for handling the browser driver if you need to pass extra details
-         - keep_alive - Whether to configure ChromeRemoteConnection to use HTTP keep-alive.
+        Starts the service and then creates new instance of chrome driver.
+
+        Args:
+            options: This takes an instance of ChromeOptions.
+            service: Service object for handling the browser driver if you need to pass extra details.
+            keep_alive: Whether to configure ChromeRemoteConnection to use HTTP keep-alive.
         """
         service = service if service else Service()
         options = options if options else Options()

py/selenium/webdriver/chromium/options.py

@@ -27,6 +27,7 @@ class ChromiumOptions(ArgOptions):
     KEY = "goog:chromeOptions"
 
     def __init__(self) -> None:
+        """Initialize ChromiumOptions with default settings."""
         super().__init__()
         self._binary_location: str = ""
         self._extension_files: list[str] = []
@@ -37,42 +38,46 @@ def __init__(self) -> None:
 
     @property
     def binary_location(self) -> str:
-        """:Returns: The location of the binary, otherwise an empty string."""
+        """Returns:
+            The location of the binary, otherwise an empty string.
+        """
         return self._binary_location
 
     @binary_location.setter
     def binary_location(self, value: str) -> None:
         """Allows you to set where the chromium binary lives.
 
-        Parameters:
-        ----------
-            value: path to the Chromium binary
+        Args:
+            value: Path to the Chromium binary.
         """
         if not isinstance(value, str):
             raise TypeError(self.BINARY_LOCATION_ERROR)
         self._binary_location = value
 
     @property
     def debugger_address(self) -> Optional[str]:
-        """:Returns: The address of the remote devtools instance."""
+        """Returns:
+            The address of the remote devtools instance.
+        """
         return self._debugger_address
 
     @debugger_address.setter
     def debugger_address(self, value: str) -> None:
         """Allows you to set the address of the remote devtools instance that
         the ChromeDriver instance will try to connect to during an active wait.
 
-        Parameters:
-        ----------
-            value: address of remote devtools instance if any (hostname[:port])
+        Args:
+            value: Address of remote devtools instance if any (hostname[:port]).
         """
         if not isinstance(value, str):
             raise TypeError("Debugger Address must be a string")
         self._debugger_address = value
 
     @property
     def extensions(self) -> list[str]:
-        """:Returns: A list of encoded extensions that will be loaded."""
+        """Returns:
+            A list of encoded extensions that will be loaded.
+        """
 
         def _decode(file_data: BinaryIO) -> str:
             # Should not use base64.encodestring() which inserts newlines every
@@ -91,9 +96,8 @@ def add_extension(self, extension: str) -> None:
         """Adds the path to the extension to a list that will be used to
         extract it to the ChromeDriver.
 
-        Parameters:
-        ----------
-            extension: path to the \\*.crx file
+        Args:
+            extension: Path to the \\*.crx file.
         """
         if extension:
             extension_to_add = os.path.abspath(os.path.expanduser(extension))
@@ -108,9 +112,8 @@ def add_encoded_extension(self, extension: str) -> None:
         """Adds Base64 encoded string with extension data to a list that will
         be used to extract it to the ChromeDriver.
 
-        Parameters:
-        ----------
-            extension: Base64 encoded string with extension data
+        Args:
+            extension: Base64 encoded string with extension data.
         """
         if extension:
             self._extensions.append(extension)
@@ -119,45 +122,44 @@ def add_encoded_extension(self, extension: str) -> None:
 
     @property
     def experimental_options(self) -> dict:
-        """:Returns: A dictionary of experimental options for chromium."""
+        """Returns:
+            A dictionary of experimental options for chromium.
+        """
         return self._experimental_options
 
     def add_experimental_option(self, name: str, value: Union[str, int, dict, list[str]]) -> None:
         """Adds an experimental option which is passed to chromium.
 
-        Parameters:
-        ----------
-          name: The experimental option name.
-          value: The option value.
+        Args:
+            name: The experimental option name.
+            value: The option value.
         """
         self._experimental_options[name] = value
 
     @property
     def enable_webextensions(self) -> bool:
-        """:Returns: Whether webextension support is enabled for Chromium-based browsers.
-        True if webextension support is enabled, False otherwise.
+        """Returns:
+            Whether webextension support is enabled for Chromium-based browsers.
+            True if webextension support is enabled, False otherwise.
         """
         return self._enable_webextensions
 
     @enable_webextensions.setter
     def enable_webextensions(self, value: bool) -> None:
         """Enables or disables webextension support for Chromium-based browsers.
 
-        Parameters:
-        ----------
-            value : bool
-                True to enable webextension support, False to disable.
+        Args:
+            value: True to enable webextension support, False to disable.
 
         Notes:
-        -----
-        - When enabled, this automatically adds the required Chromium flags:
-            - --enable-unsafe-extension-debugging
-            - --remote-debugging-pipe
-        - When disabled, this removes BOTH flags listed above, even if they were manually added via add_argument()
-          before enabling webextensions.
-        - Enabling --remote-debugging-pipe makes the connection b/w chromedriver
-          and the browser use a pipe instead of a port, disabling many CDP functionalities
-          like devtools
+            - When enabled, this automatically adds the required Chromium flags:
+                - --enable-unsafe-extension-debugging
+                - --remote-debugging-pipe
+            - When disabled, this removes BOTH flags listed above, even if they were manually added via add_argument()
+              before enabling webextensions.
+            - Enabling --remote-debugging-pipe makes the connection b/w chromedriver
+              and the browser use a pipe instead of a port, disabling many CDP functionalities
+              like devtools
         """
         self._enable_webextensions = value
         if value:
@@ -174,11 +176,10 @@ def enable_webextensions(self, value: bool) -> None:
                     self._arguments.remove(flag)
 
     def to_capabilities(self) -> dict:
-        """Creates a capabilities with all the options that have been set
+        """Creates a capabilities with all the options that have been set.
 
         Returns:
-        -------
-            dict : a dictionary with all set options
+            A dictionary with all set options.
         """
         caps = self._caps
         chrome_options = self.experimental_options.copy()

py/selenium/webdriver/firefox/firefox_binary.py

@@ -34,11 +34,11 @@ class FirefoxBinary:
     def __init__(self, firefox_path=None, log_file=None):
         """Creates a new instance of Firefox binary.
 
-        :Args:
-         - firefox_path - Path to the Firefox executable. By default, it will be detected from the standard locations.
-         - log_file - A file object to redirect the firefox process output to. It can be sys.stdout.
-                      Please note that with parallel run the output won't be synchronous.
-                      By default, it will be redirected to /dev/null.
+        Args:
+            firefox_path: Path to the Firefox executable. By default, it will be detected from the standard locations.
+            log_file: A file object to redirect the firefox process output to. It can be sys.stdout.
+                Please note that with parallel run the output won't be synchronous.
+                By default, it will be redirected to /dev/null.
         """
         self._start_cmd = firefox_path
         # We used to default to subprocess.PIPE instead of /dev/null, but after

py/selenium/webdriver/firefox/webdriver.py

@@ -44,10 +44,10 @@ def __init__(
         """Creates a new instance of the Firefox driver. Starts the service and
         then creates new instance of Firefox driver.
 
-        :Args:
-         - options - Instance of ``options.Options``.
-         - service - (Optional) service instance for managing the starting and stopping of the driver.
-         - keep_alive - Whether to configure remote_connection.RemoteConnection to use HTTP keep-alive.
+        Args:
+            options: Instance of ``options.Options``.
+            service: (Optional) service instance for managing the starting and stopping of the driver.
+            keep_alive: Whether to configure remote_connection.RemoteConnection to use HTTP keep-alive.
         """
 
         self.service = service if service else Service()
@@ -159,11 +159,11 @@ def get_full_page_screenshot_as_file(self, filename) -> bool:
         image file. Returns False if there is any IOError, else returns True.
         Use full paths in your filename.
 
-        :Args:
-         - filename: The full path you wish to save your screenshot to. This
-           should end with a `.png` extension.
+        Args:
+            filename: The full path you wish to save your screenshot to. This
+                should end with a `.png` extension.
 
-        :Usage:
+        Usage:
             ::
 
                 driver.get_full_page_screenshot_as_file("/Screenshots/foo.png")
@@ -188,11 +188,11 @@ def save_full_page_screenshot(self, filename) -> bool:
         image file. Returns False if there is any IOError, else returns True.
         Use full paths in your filename.
 
-        :Args:
-         - filename: The full path you wish to save your screenshot to. This
-           should end with a `.png` extension.
+        Args:
+            filename: The full path you wish to save your screenshot to. This
+                should end with a `.png` extension.
 
-        :Usage:
+        Usage:
             ::
 
                 driver.save_full_page_screenshot("/Screenshots/foo.png")