Doc fixes

Author: VladimirPodolian

docs/source/kitchen_sink/index.md

@@ -15,13 +15,13 @@ scrolls
 
 ## Overview
 
-This section documents the essential mini-objects, dataclasses, 
-and helper functions used throughout the framework.
-These building blocks are designed to provide a modular, 
-reusable, and easy-to-understand interface for common 
-operations, data structures, and utilities.
+The **Kitchen Sink** section documents essential mini-objects, dataclasses, 
+and helper functions used throughout the framework. 
+These components serve as modular, reusable, and easy-to-understand building 
+blocks for common operations, data structures, and utilities.
+
+### Available Components
 
-This section covers features and behaviour of `Group` class detail:
 - {doc}`Size Dataclass <./size>`
 - {doc}`Location Dataclass <./location>`
 - {doc}`Driver Dataclass <./driver_container>`

docs/source/kitchen_sink/locator.md

@@ -1,7 +1,42 @@
 # Locator dataclass
 
+## Overview
+
+The `Locator` class is designed to provide a flexible mechanism for managing locators in a unified way.
+This class supports different locator types for various platforms and devices, including `desktop`, `mobile`, and `tablet` environments. 
+The `Locator` class is particularly useful in automation frameworks where locators need to be adapted based on the specific driver 
+and capabilities being used.
+
+This object and its usage aim to reduce the redundancy of creating multiple attributes for different platforms. 
+By centralizing locators in a single `Locator` object, it simplifies the codebase and enhances maintainability.
+
+<br>
+
+## Interface
+
 ```{eval-rst}  
 .. autoclass:: mops.mixins.objects.locator.Locator
    :undoc-members:
    :inherited-members:
 ```
+
+<br>
+
+## Usage
+
+The `Locator` class is designed to be flexible and adaptive, making it suitable for various automation scenarios. 
+Here’s how the attributes work together:
+
+- **`loc_type`** is optional. If not specified, the system will attempt to automatically select the appropriate locator type based on the provided locator.
+- **`default`** will be used if no specific locator is provided for the current platform or device.
+
+<br>
+
+### Example
+
+```python
+# Providing string parameter instead of Locator object
+button = Element('.button', name='button')
+
+search_button = Element(Locator(desktop='.search', mobile='.mobile.search'), name='search button')
+```

docs/source/other/locator_object.md

@@ -3,7 +3,7 @@
 ## Overview
 
 ```{attention}
-Supported for `allure` and `pytest` frameworks.
+Supported for [allure](https://pypi.org/project/allure-pytest/) and [pytest](https://pypi.org/project/pytest/) frameworks.
 - `allure` for reporting;
 - `pytest` for sreenshot name definition.
 ```
@@ -20,39 +20,8 @@ The class also handles dynamic thresholds, image comparison metrics, and can gen
 .. autoclass:: mops.visual_comparison.VisualComparison 
    :exclude-members: calculate_threshold 
    :members: assert_screenshot
-   
-   .. attribute:: visual_regression_path: str = ''
-      -   Path where visual regression images (reference, output, and diff) will be stored. 
-   
-   .. attribute:: test_item: pytest.Item = None
-      -   The pytest `request.node.` object associated with the visual comparison.
-   
-   .. attribute:: attach_diff_image_path: bool = False
-      -   Flag to determine whether to attach the diff image path to the report. 
-   
-   .. attribute:: skip_screenshot_comparison: bool = False
-      -   If set to `True`, the screenshot comparison will be skipped. 
-   
-   .. attribute:: visual_reference_generation: bool = False
-      -   Enables generation of visual references. 
-   
-   .. attribute:: hard_visual_reference_generation: bool = False
-      -   Forces generation of visual references, replacing existing ones. 
-   
-   .. attribute:: soft_visual_reference_generation: bool = False
-      -   Allows generation of visual references only if they do not exist. 
-   
-   .. attribute:: default_delay: Union[int, float] = 0.75
-      -   Default delay before taking a screenshot. 
-   
-   .. attribute:: default_threshold: Union[int, float] = 0
-      -   Default threshold for image comparison. 
-   
-   .. attribute:: dynamic_threshold_factor: int = 0
-      -   Factor for dynamically calculating threshold based on image size. 
-   
-   .. attribute:: diff_color_scheme: tuple = (0, 255, 0)
-      -   Color scheme used for highlighting differences in images. 
+   :undoc-members:
+   :inherited-members:
 ```
 
 <br>

docs/source/other/visual_comparison.md

@@ -30,7 +30,6 @@ caption: Other
 
 other/objects_initialisation
 other/visual_comparison
-other/locator_object
 ```
 
 ```{toctree}

docs/source/toc.md

@@ -1,25 +1,59 @@
 from dataclasses import dataclass
-from typing import Optional, Any
-
-
-def take_locator_type(locator: Any):
-    """
-    Safe take locator type from given object
-
-    :param locator:
-    :return:
-    """
-    return locator.loc_type if type(locator) is Locator else None
+from typing import Optional, Any, Union
 
 
 @dataclass
 class Locator:
     """ Represents a WEB UI element locator with platform-specific variations. """
 
     default: Optional[str] = None
+    """
+    All: The default locator for the object, used by default if no other locators are specified 
+     or if no specific platform/device type is detected.
+    """
     loc_type: Optional[str] = None
+    """
+    Selenium & Appium only: Specifies the locator type 
+    (e.g., :obj:`~selenium.webdriver.common.by.By.CSS_SELECTOR`, :obj:`~selenium.webdriver.common.by.By.XPATH`, etc.).  
+
+    If not provided, the locator type is automatically determined based on the given locator.
+    """
+
     desktop: Optional[str] = None
+    """
+    All: The locator for desktop environments, typically used for browsers on desktop platforms.
+    """
+
     mobile: Optional[str] = None
+    """
+    All: The locator for general mobile environments, used for mobile platforms other than iOS and Android,
+     as well as for mobile resolutions of desktop browsers.
+    """
+
     tablet: Optional[str] = None
+    """
+    Appium only: The locator specifically for tablet devices, useful for web and app automation on tablets. 
+    The "is_tablet: True" desired_capability is required.
+    """
+
     ios: Optional[str] = None
+    """
+    Appium only: The locator specifically for iOS devices, 
+     allowing for targeting locators specific to iOS applications.
+    """
+
     android: Optional[str] = None
+    """
+    Appium only: The locator specifically for Android devices, 
+     allowing for targeting locators specific to Android applications.
+    """
+
+
+def take_locator_type(locator: Union[Locator, str]) -> Union[str, None]:
+    """
+    Safe take locator type from given object.
+
+    :param locator: a Locator object or string containing locator.
+    :return: locator type if given arg is Locator object.
+    """
+    return locator.loc_type if type(locator) is Locator else None