[py] Cleanup and convert more doctrings to google-style

[iampopovich]

User description

🔗 Related Issues

relates to #11442

💥 What does this PR do?

This pull request focuses on improving the clarity and consistency of docstrings and documentation throughout several core Selenium Python modules. The changes modernize docstring formatting, replace legacy usage examples with standardized sections, and simplify property documentation for maintainability and readability.

Key changes include:

Docstring Standardization and Improvements:

• Updated all method and class docstrings in action_chains.py, alert.py, log.py, and proxy.py to use the standard Args: and Example: (where appropriate) sections, replacing the older :Args: and :Usage: formats for better readability and consistency. [1] [2] [3] [4] [5] [6] [7] [8] [9] [10] [11] [12] [13] [14] [15] [16] [17] [18] [19] [20] [21] [22] [23] [24]

Property and Attribute Documentation Simplification:

• Replaced verbose, repetitive property docstrings in the Proxy class (proxy.py) with concise one-line descriptions for each proxy attribute, making the code easier to maintain and understand.

Example Section Modernization:

• Updated usage examples in alert.py and log.py to use an Example: section instead of the previous :Usage: format, aligning with modern Python documentation standards. [1] [2] [3] [4]

Overall, these changes bring the codebase's documentation up to date with best practices, making it more accessible for both new and experienced contributors.

🔧 Implementation Notes

💡 Additional Considerations

🔄 Types of changes

• Cleanup (formatting, renaming)

---

PR Type

Documentation

---

Description

• Standardized docstring format from :Args: to Args: across Python modules

• Replaced :Usage: sections with Example: for consistency

• Simplified property docstrings in proxy and timeouts classes

• Updated method documentation in action chains, alert, and other core classes

• Improved docstring formatting to follow Google style guide conventions

---

Diagram Walkthrough

flowchart LR
  A["Legacy Format<br/>:Args: :Usage:"] -->|Refactor| B["Google Style<br/>Args: Example:"]
  B -->|Applied to| C["Action Chains<br/>Alert Log Proxy"]
  B -->|Applied to| D["WebDriver Classes<br/>Options Services"]
  B -->|Applied to| E["Support Classes<br/>Select RelativeBy"]

Loading

File Walkthrough

Relevant files

Documentation

22 files action_chains.py Converted docstrings to Google style format                            +60/-60  alert.py Updated Args and Usage to Example format                                  +6/-8      log.py Replaced Usage sections with Example format                            +5/-11    proxy.py Simplified property docstrings significantly                          +16/-137 selenium_manager.py Standardized Args and Returns documentation                            +14/-8    timeouts.py Simplified property docstrings and Args format                      +13/-50  utils.py Updated Args and Returns to Google style                                  +14/-14  virtual_authenticator.py Converted Args and Returns to Google style                              +22/-22  webdriver.py Updated docstring to Google style format                                  +9/-6      options.py Standardized docstring format and improved clarity              +17/-9    service.py Converted Args to Google style format                                        +10/-10  webdriver.py Updated docstring to Google style format                                  +4/-4      errorhandler.py Improved docstring clarity and Args format                              +8/-7      switch_to.py Replaced Usage with Example and standardized Args                +16/-30  webdriver.py Updated docstring to Google style format                                  +5/-5      event_firing_webdriver.py Standardized Args and improved docstring formatting            +12/-11  relative_locator.py Converted Parameters to Args and standardized format          +55/-104 select.py Updated Args and Raises to Google style format                      +26/-21  options.py Standardized Args and Returns documentation                            +12/-7    webdriver.py Updated docstring to Google style format                                  +3/-3      options.py Converted Args to Google style format                                        +2/-2      webdriver.py Updated docstring to Google style format                                  +3/-3

---

[selenium-ci]

Thank you, @iampopovich for this code suggestion.

The support packages contain example code that many users find helpful, but they do not necessarily represent
the best practices for using Selenium, and the Selenium team is not currently merging changes to them.

After reviewing the change, unless it is a critical fix or a feature that is needed for Selenium
to work, we will likely close the PR.

We actively encourage people to add the wrapper and helper code that makes sense for them to their own frameworks.
If you have any questions, please contact us

[iampopovich]

@cgoldberg check please
sorry for the bigger files batch
i decided not to split these changes into parts , cause they are similar

[qodo-merge-pro]

PR Code Suggestions ✨

No code suggestions found for the PR.

[cgoldberg]

LGTM. Thanks!
I'll merge it as soon as the formatter runs in CI.