Merge pull request #37 from thalissonvs/doc-improvements

docs: improve documentation for clarity

Author: thalissonvs

pydoll/browser/base.py

@@ -60,14 +60,36 @@ def __init__(
         self._pages = []
 
     async def __aenter__(self):
+        """
+        Async context manager entry point.
+
+        Returns:
+            Browser: The browser instance.
+        """
         return self
 
     async def __aexit__(self, exc_type, exc_val, exc_tb):
+        """
+        Async context manager exit point.
+
+        Args:
+            exc_type: The exception type, if raised.
+            exc_val: The exception value, if raised.
+            exc_tb: The traceback, if an exception was raised.
+        """
         await self.stop()
         await self._connection_handler.close()
 
     async def start(self) -> None:
-        """Método principal para iniciar o navegador."""
+        """
+        Main method to start the browser.
+
+        This method initializes the browser process and configures
+        all necessary settings to create a working browser instance.
+
+        Returns:
+            None
+        """
         binary_location = (
             self.options.binary_location or self._get_default_binary_location()
         )
@@ -108,6 +130,9 @@ async def get_page(self) -> Page:
         """
         Retrieves a Page instance for an existing page in the browser.
         If no pages are open, a new page will be created.
+
+        Returns:
+            Page: A Page instance connected to an existing or new browser page.
         """
         page_id = (
             await self.new_page() if not self._pages else self._pages.pop()
@@ -153,7 +178,9 @@ async def on(
 
         Args:
             event_name (str): Name of the event to listen for.
-            callback (Callable): function to be called when the event occurs.
+            callback (callable): Function to be called when the event occurs.
+            temporary (bool): If True, the callback will be removed after it's
+                triggered once. Defaults to False.
 
         Returns:
             int: The ID of the registered callback.
@@ -174,8 +201,12 @@ async def new_page(self, url: str = ''):
         """
         Opens a new page in the browser.
 
+        Args:
+            url (str): Optional initial URL to navigate to.
+                Defaults to empty string.
+
         Returns:
-            Page: The new page instance.
+            str: The ID of the new page.
         """
         response = await self._execute_command(
             TargetCommands.create_target(url)
@@ -422,17 +453,40 @@ async def _continue_request_auth_required(
         await self.disable_fetch_events()
 
     async def _init_first_page(self):
+        """
+        Initializes the first page in the browser.
+
+        This method obtains the first valid page from available targets
+        and stores its ID for later use.
+
+        Returns:
+            None
+        """
         pages = await self.get_targets()
         valid_page = await self._get_valid_page(pages)
         self._pages.append(valid_page)
 
     async def _verify_browser_running(self):
-        """Verifica se o navegador está rodando."""
+        """
+        Verifies if the browser is running.
+
+        Raises:
+            BrowserNotRunning: If the browser failed to start.
+        """
         if not await self._is_browser_running():
             raise exceptions.BrowserNotRunning('Failed to start browser')
 
     async def _configure_proxy(self, private_proxy, proxy_credentials):
-        """Configura o proxy, se necessário."""
+        """
+        Configures proxy settings if needed.
+
+        Args:
+            private_proxy: Boolean indicating if a private proxy is enabled.
+            proxy_credentials: Tuple containing proxy username and password.
+
+        Returns:
+            None
+        """
         if private_proxy:
             await self.enable_fetch_events(handle_auth_requests=True)
             await self.on(
@@ -452,17 +506,28 @@ async def _configure_proxy(self, private_proxy, proxy_credentials):
 
     @staticmethod
     def _is_valid_page(page: dict) -> bool:
-        """Verifica se uma página é uma nova aba válida."""
+        """
+        Verifies if a page is a valid new tab.
+
+        Args:
+            page (dict): Dictionary containing page information.
+
+        Returns:
+            bool: True if the page is a valid new tab, False otherwise.
+        """
         return page.get('type') == 'page' and 'chrome://newtab/' in page.get(
             'url', ''
         )
 
     async def _get_valid_page(self, pages) -> str:
         """
-        Obtém o ID de uma página válida ou cria uma nova.
+        Gets the ID of a valid page or creates a new one.
+
+        Args:
+            pages (list): List of page dictionaries to check for validity.
 
         Returns:
-            str: targetId da página existente ou nova
+            str: The target ID of an existing or new page.
         """
         valid_page = next(
             (page for page in pages if self._is_valid_page(page)), None
@@ -505,7 +570,15 @@ async def _execute_command(self, command: str):
         )
 
     def _setup_user_dir(self):
-        """Prepara o diretório de dados do usuário, se necessário."""
+        """
+        Prepares the user data directory if needed.
+
+        This method creates a temporary directory for browser data if
+        no user directory is specified in the browser options.
+
+        Returns:
+            None
+        """
         temp_dir = self._temp_directory_manager.create_temp_dir()
         if '--user-data-dir' not in [
             arg.split('=')[0] for arg in self.options.arguments

pydoll/browser/chrome.py

@@ -7,15 +7,44 @@
 
 
 class Chrome(Browser):
+    """
+    A class that implements the Chrome browser functionality.
+
+    This class provides specific implementation for launching and
+    controlling Google Chrome browsers.
+    """
+
     def __init__(
         self,
         options: Optional[Options] = None,
         connection_port: Optional[int] = None,
     ):
+        """
+        Initializes the Chrome browser instance.
+
+        Args:
+            options (Options | None): An instance of Options class to configure
+                the browser. If None, default options will be used.
+            connection_port (int): The port to connect to the browser.
+                Defaults to 9222.
+        """
         super().__init__(options, connection_port)
 
     @staticmethod
     def _get_default_binary_location():
+        """
+        Gets the default location of the Chrome browser executable.
+
+        This method determines the default Chrome executable path based
+        on the operating system.
+
+        Returns:
+            str: The path to the Chrome browser executable.
+
+        Raises:
+            ValueError: If the operating system is not supported or
+                the browser executable is not found at the default location.
+        """
         os_name = platform.system()
         browser_paths = {
             'Windows':