Home Original page

[py] Update docstrings style according to google guideline by iampopovich · Pull Request #16445 · SeleniumHQ/selenium

User description

🔗 Related Issues

relates to #16427

💥 What does this PR do?

https://github.com/google/styleguide/blob/gh-pages/pyguide.md

This pull request focuses on improving the clarity and consistency of docstrings across several Selenium WebDriver Python modules, especially for Chromium, Chrome, Edge, and Firefox classes. The changes modernize docstring formats to follow a more standardized "Args"/"Returns"/"Example" style, making the documentation easier to read and understand for both users and contributors.

Docstring Standardization and Clarification

  • Updated constructor and method docstrings in chromium/webdriver.py and chrome/webdriver.py to use consistent "Args" and "Returns" sections, replacing older ":Args:" and ":Returns:" formats. This includes clearer descriptions and examples for parameters and return values. [1] [2]
  • Improved docstrings in chromium/options.py for properties and methods, ensuring each parameter and return value is clearly documented using the "Args" and "Returns" format. [1] [2] [3] [4] [5] [6] [7]

Edge-Specific Documentation Improvements

  • Enhanced docstrings in edge/options.py and edge/service.py to clarify initialization parameters, property purposes, and method return values, all using the updated documentation style. [1] [2] [3] [4] [5]

Other Browser-Specific Updates

  • Updated the FirefoxBinary class constructor in firefox/firefox_binary.py to use the new docstring format for parameter documentation.

Minor Enhancements

  • Added explicit docstrings to methods that previously lacked them, such as those raising NotImplementedError in chromium/webdriver.py, to clarify their current status.

These changes collectively make the codebase's documentation more accessible and maintainable, which will help both new and experienced developers understand and use these APIs more effectively.

🔧 Implementation Notes

💡 Additional Considerations

🔄 Types of changes

  • Cleanup (formatting, renaming)

PR Type

Documentation

Description

  • Standardized Python docstrings to Google style guide format

  • Updated Args/Returns/Example sections across WebDriver modules

  • Enhanced clarity for Chromium, Chrome, Edge, and Firefox classes

  • Improved parameter descriptions and usage examples

Diagram Walkthrough

flowchart LR
  A["Old docstring format"] --> B["Google style format"]
  B --> C["Chrome/Chromium modules"]
  B --> D["Edge modules"]
  B --> E["Firefox modules"]
  C --> F["Improved Args/Returns"]
  D --> F
  E --> F
Loading

File Walkthrough
Relevant files
Documentation
webdriver.py
Standardize Chrome WebDriver docstrings                                   

py/selenium/webdriver/chrome/webdriver.py

  • Updated __init__ docstring to Google style format
  • Changed :Args: to Args: with proper indentation
  • Improved parameter descriptions clarity
 +7/-6     
options.py
Refactor ChromiumOptions docstrings to Google style           

py/selenium/webdriver/chromium/options.py

  • Added __init__ docstring
  • Converted all property and method docstrings to Google style
  • Updated binary_location, debugger_address, extensions properties
  • Improved add_extension, add_encoded_extension method docs
  • Enhanced enable_webextensions with detailed notes
 +38/-37 
webdriver.py
Standardize ChromiumDriver method docstrings                         

py/selenium/webdriver/chromium/webdriver.py

  • Updated __init__ to use Args: format
  • Converted launch_app, get_network_conditions, set_network_conditions
    docs
  • Improved set_permissions, execute_cdp_cmd with Example sections
  • Updated Cast-related methods and log methods
  • Added docstrings for download_file, get_downloadable_files,
    delete_downloadable_files
 +53/-54 
options.py
Update Edge Options docstrings to Google style                     

py/selenium/webdriver/edge/options.py

  • Added __init__ docstring
  • Updated use_webview property with Returns section
  • Enhanced to_capabilities and default_capabilities docs
 +17/-2   
service.py
Refactor Edge Service docstrings                                                 

py/selenium/webdriver/edge/service.py

  • Converted class docstring from :param: to Args: format
  • Added __init__ docstring
  • Updated service_args property with Returns and setter docs
 +19/-6   
firefox_binary.py
Standardize Firefox binary docstrings                                       

py/selenium/webdriver/firefox/firefox_binary.py

  • Updated __init__ docstring from :Args: to Args: format
  • Improved parameter descriptions for firefox_path and log_file
 +5/-5     
webdriver.py
Refactor Firefox WebDriver docstrings to Google style       

py/selenium/webdriver/firefox/webdriver.py

  • Updated __init__ to Google style format
  • Added docstring for set_context method
  • Converted context, install_addon, uninstall_addon docs
  • Updated screenshot methods with Args/Returns/Example sections
  • Added docstrings for unimplemented download methods
 +45/-36