[py] Fix docstring issues that sphinx complains about

[cgoldberg]

User description

Motivation and Context

This is a bunch of small fixes to docstrings that sphinx keeps complaining about when generating the Python docs. There are still a ton of warnings when building the docs, but this at least fixes some of them.

This also includes some minor changes suggested by the bot below in comments.

Types of changes

• Bug fix (non-breaking change which fixes an issue)
• New feature (non-breaking change which adds functionality)
• Breaking change (fix or feature that would cause existing functionality to change)

Checklist

• I have read the contributing document.
• My change requires a change to the documentation.
• I have updated the documentation accordingly.
• I have added tests to cover my changes.
• All new and existing tests passed.

---

PR Type

Documentation

---

Description

• Fixed inconsistent docstring formatting across multiple files.

• Standardized section headers in docstrings for better Sphinx compatibility.

• Improved clarity and consistency in parameter and return descriptions.

---

Changes walkthrough 📝

Relevant files

Documentation

15 files action_builder.py Standardized docstring headers for methods.                            +5/-5      by.py Fixed docstring formatting for class attributes.                  +1/-1      options.py Standardized docstring headers and usage examples.              +78/-78  print_page_options.py Improved docstring formatting for print options.                  +68/-68  proxy.py Fixed docstring formatting for proxy settings.                      +40/-40  timeouts.py Standardized docstring headers for timeout descriptors.    +10/-10  options.py Standardized docstring headers for IE options.                      +68/-68  shadowroot.py Fixed docstring formatting for shadow root methods.            +2/-2      webdriver.py Standardized docstring headers for WebDriver methods.        +29/-29  webelement.py Improved docstring formatting for WebElement methods.        +9/-9      options.py Standardized docstring headers for Safari options.              +12/-12  expected_conditions.py Fixed docstring formatting for expected conditions.            +31/-31  relative_locator.py Standardized docstring headers for relative locator methods. +8/-8      wait.py Improved docstring formatting for wait methods.                    +3/-3      index.rst Fixed minor formatting issue in documentation index.          +1/-1

---

Need help?

Type /help how to ... in the comments thread for any questions about Qodo Merge usage.

Check out the documentation for more information.

[qodo-merge-pro]

PR Reviewer Guide 🔍

Here are some key observations to aid the review process:

⏱️ Estimated effort to review: 2 🔵🔵⚪⚪⚪

🧪 No relevant tests

🔒 No security concerns identified

⚡ Recommended focus areas for review Formatting Inconsistency The formatting for the Usage and Parameters sections in the script timeout docstring is inconsistent with other sections. The plus signs are missing before the section headers. Usage: ------ - Get - `self.script` - Set - `self.script` = `value` Parameters: ----------- `value`: `float` Documentation Error The socks_username property docstring incorrectly states it "Gets and Sets socks_password" instead of "socks_username". """Gets and Sets `socks_password` Usage: ------ - Get - `self.socks_password` - Set - `self.socks_password` = `value` Parameters: ----------- `value`: `str` """

[qodo-merge-pro]

PR Code Suggestions ✨

Latest suggestions up to 2fe8e77

Category	Suggestion	Impact
General	Fix incorrect return type The return type in the docstring for web_socket_url getter is incorrectly specified as bool when it should be str or None to match the parameter type and actual implementation. py/selenium/webdriver/common/options.py [399-417] web_socket_url = _BaseOptionsDescriptor("webSocketUrl") """Gets and Sets WebSocket URL. Usage: ------ - Get - `self.web_socket_url` - Set - `self.web_socket_url` = `value` Parameters: ----------- `value`: `str` Returns: -------- - Get - - `bool` + - `str` or `None` - Set + - `None` """ [To ensure code accuracy, apply this suggestion manually] Suggestion importance[1-10]: 8 __ Why: The suggestion correctly identifies a documentation error where the return type for the web_socket_url getter is incorrectly specified as 'bool' when it should be 'str' or 'None' to match the parameter type. This is an important fix for API documentation accuracy.	Medium
More

---

Previous suggestions

✅ Suggestions up to commit 9b4b273

Category	Suggestion	Impact
General	✅ Fix incorrect docstring description The docstring for web_socket_url incorrectly states it's for accepting insecure certificates. It should describe WebSocket URL functionality instead. py/selenium/webdriver/common/options.py [287-288] web_socket_url = _BaseOptionsDescriptor("webSocketUrl") -"""Gets and Set whether the session accepts insecure certificates. +"""Gets and Sets WebSocket URL. [Suggestion has been applied] Suggestion importance[1-10]: 8 __ Why: The suggestion correctly identifies a significant error in the docstring where the WebSocket URL property is incorrectly described as controlling insecure certificates acceptance. This is a clear documentation bug that could mislead developers.	Medium
	✅ Fix incorrect parameter type Suggestion Impact: The commit changed the parameter type in the documentation from bool to str as suggested. It also fixed the description of the web_socket_url property. code diff: - """Gets and Set whether the session accepts insecure certificates. + """Gets and Sets WebSocket URL. Usage: ------ @@ -430,7 +430,7 @@ Parameters: ----------- - `value`: `bool` + `value`: `str` The parameter and return type for web_socket_url are incorrectly documented as bool when they should be str based on the property name and its usage. py/selenium/webdriver/common/options.py [421-439] web_socket_url = _BaseOptionsDescriptor("webSocketUrl") """Gets and Sets WebSocket URL. Usage: ------ - Get - `self.web_socket_url` - Set - `self.web_socket_url` = `value` Parameters: ----------- -`value`: `bool` +`value`: `str` Returns: -------- - Get - - `bool` + - `str` - Set - `None` """ Suggestion importance[1-10]: 7 __ Why: The suggestion correctly identifies that the parameter and return types for web_socket_url are incorrectly documented as boolean when they should be strings. This is an important documentation fix that prevents confusion about the expected data types.	Medium
Possible issue	✅ Remove duplicate property declaration Suggestion Impact: The commit removed the first instance of the web_socket_url property declaration (lines 5-25 in the diff), which was one of the duplicates identified in the suggestion. The suggestion wanted to remove the second instance, but the commit removed the first one instead, achieving the same goal of eliminating the duplication. code diff: - web_socket_url = _BaseOptionsDescriptor("webSocketUrl") - """Gets and Set whether the session accepts insecure certificates. - - Usage: - ------ - - Get - - `self.web_socket_url` - - Set - - `self.web_socket_url` = `value` - - Parameters: - ----------- - `value`: `str` - - Returns: - -------- - - Get - - `str` or `None` - - Set - - `None` - """ The web_socket_url property is duplicated in the BaseOptions class. There are two identical property declarations at lines 287 and 421, which could cause confusion or unexpected behavior. py/selenium/webdriver/common/options.py [421-441] -web_socket_url = _BaseOptionsDescriptor("webSocketUrl") -"""Gets and Sets WebSocket URL. +# Remove the duplicate declaration, keeping only one instance of web_socket_url -Usage: ------- -- Get - - `self.web_socket_url` -- Set - - `self.web_socket_url` = `value` - -Parameters: ------------ -`value`: `bool` - -Returns: --------- -- Get - - `bool` -- Set - - `None` -""" - [Suggestion has been applied] Suggestion importance[1-10]: 9 __ Why: The suggestion correctly identifies a duplicate declaration of the web_socket_url property in the BaseOptions class. This duplication (at lines 287-305 and 421-440) could lead to unexpected behavior as the second declaration would override the first one. Removing the duplicate is critical for proper class functionality.	High

✅ Suggestions up to commit b5b4e01

Category	Suggestion	Impact
General	✅ Fix inconsistent docstring formatting Suggestion Impact: The commit implemented the exact change suggested, adding one more dash to the 'Example:' section underline to make it consistent with the 'Parameters:' section code diff: - ------- + -------- The indentation in the docstring is inconsistent. The "Example:" section has one less dash than the "Parameters:" section, which could cause issues with Sphinx documentation generation. py/selenium/webdriver/remote/webdriver.py [814-824] def set_page_load_timeout(self, time_to_wait: float) -> None: """Sets the amount of time to wait for a page load to complete before throwing an error. Parameters: ----------- time_to_wait : float - The amount of time to wait (in seconds) Example: - ------- + -------- >>> driver.set_page_load_timeout(30) """ Suggestion importance[1-10]: 5 __ Why: The suggestion correctly identifies an inconsistency in the docstring formatting where the "Example:" section uses 7 dashes (-------) while the "Parameters:" section uses 9 dashes (-----------). This inconsistency could affect documentation generation with tools like Sphinx.	Low