chore: Updates docstring (appium#533)

* Updates docstring

* Add description to Returns field

* Remove type from docstring

Since type hint already added to args

* Set default lang to en

* Change usage style in docstring

* Updates

* Remove rtype

unnecessary anymore since type hint works for auto completion

* tweak

* Update return type

* Restore types for keyword args

* Remove types from Return field

Except for property and TypeVar

Author: ki4070ma

appium/common/exceptions.py

@@ -21,7 +21,7 @@ class NoSuchContextException(InvalidSwitchToTargetException):
     To find the current set of active contexts, you can get a list
     of the active contexts in the following way:
 
-        print driver.contexts
+        print(driver.contexts)
 
     """
     pass

appium/common/helper.py

@@ -21,10 +21,10 @@ def extract_const_attributes(cls: type) -> Dict[str, Any]:
     """Return dict with constants attributes and values in the class(e.g. {'VAL1': 1, 'VAL2': 2})
 
     Args:
-        cls (type): Class to be extracted constants
+        cls: Class to be extracted constants
 
     Returns:
-        dict: dict with constants attributes and values in the class
+        dict with constants attributes and values in the class
     """
     return dict([(attr, value) for attr, value in vars(cls).items()
                  if not callable(getattr(cls, attr)) and attr.isupper()])

appium/webdriver/appium_service.py

@@ -128,9 +128,9 @@ def start(self, **kwargs: Any) -> sp.Popen:
                 which is inherited from the parent process is assigned by default.
             node (str): The full path to the main NodeJS executable. The service will try
                 to retrieve it automatically by default.
-            stdout: Check on the documentation for subprocess.Popen for more details.
+            stdout (int): Check on the documentation for subprocess.Popen for more details.
                 The default value is subprocess.PIPE.
-            stderr: Check on the documentation for subprocess.Popen for more details.
+            stderr (int): Check on the documentation for subprocess.Popen for more details.
                 The default value is subprocess.PIPE.
             timeout_ms (int): The maximum time to wait until Appium process starts listening
                 for HTTP connections. If set to zero or a negative number then no wait will be applied.
@@ -143,10 +143,8 @@ def start(self, **kwargs: Any) -> sp.Popen:
                 about possible arguments and their values.
 
         Returns:
-            subprocess.Popen instance: You can use Popen.communicate interface
-                or stderr/stdout properties of the instance
-                (stdout/stderr must not be set to None in such case)
-                in order to retrieve the actual process output.
+            You can use Popen.communicate interface or stderr/stdout properties
+            of the instance (stdout/stderr must not be set to None in such case) in order to retrieve the actual process output.
         """
         self.stop()
 
@@ -182,7 +180,7 @@ def stop(self) -> bool:
         or has been already stopped.
 
         Returns:
-            bool: `True` if the service was running before being stopped
+            `True` if the service was running before being stopped
         """
         is_terminated = False
         if self.is_running:
@@ -197,7 +195,7 @@ def is_running(self) -> bool:
         """Check if the service is running.
 
         Returns:
-            bool: `True` or `False`
+            bool: `True` if the service is running
         """
         return self._process is not None and self._process.poll() is None
 

appium/webdriver/common/multi_action.py

@@ -41,18 +41,17 @@ def add(self, *touch_actions: 'TouchAction') -> None:
         """Add TouchAction objects to the MultiAction, to be performed later.
 
         Args:
-            touch_actions (`TouchAction`): one or more TouchAction objects describing a chain of actions to be performed by one finger
+            touch_actions: one or more TouchAction objects describing a chain of actions to be performed by one finger
 
         Usage:
-            a1 = TouchAction(driver)
-
-            a1.press(el1).move_to(el2).release()
-
-            a2 = TouchAction(driver)
-
-            a2.press(el2).move_to(el1).release()
-
-            MultiAction(driver).add(a1, a2)
+            | a1 = TouchAction(driver)
+            | a1.press(el1).move_to(el2).release()
+            | a2 = TouchAction(driver)
+            | a2.press(el2).move_to(el1).release()
+            | MultiAction(driver).add(a1, a2)
+
+        Returns:
+            `MultiAction`: Self instance
         """
         for touch_action in touch_actions:
             if self._touch_actions is None:
@@ -64,15 +63,14 @@ def perform(self: T) -> T:
         """Perform the actions stored in the object.
 
         Usage:
-            a1 = TouchAction(driver)
-
-            a1.press(el1).move_to(el2).release()
-
-            a2 = TouchAction(driver)
-
-            a2.press(el2).move_to(el1).release()
-
-            MultiAction(driver).add(a1, a2).perform()
+            | a1 = TouchAction(driver)
+            | a1.press(el1).move_to(el2).release()
+            | a2 = TouchAction(driver)
+            | a2.press(el2).move_to(el1).release()
+            | MultiAction(driver).add(a1, a2).perform()
+
+        Returns:
+            `MultiAction`: Self instance
         """
         self._driver.execute(Command.MULTI_ACTION, self.json_wire_gestures)
 

appium/webdriver/common/touch_action.py

@@ -46,12 +46,12 @@ def tap(self: T, element: Optional['WebElement'] = None, x: Optional[int]
         """Perform a tap action on the element
 
         Args:
-            element (`appium.webdriver.webelement.WebElement`): the element to tap
-            x (:obj:`int`, optional): x coordinate to tap, relative to the top left corner of the element.
-            y (:obj:`int`, optional): y coordinate. If y is used, x must also be set, and vice versa
+            element: the element to tap
+            x : x coordinate to tap, relative to the top left corner of the element.
+            y : y coordinate. If y is used, x must also be set, and vice versa
 
         Returns:
-            `TouchAction`: self instance
+            `TouchAction`: Self instance
         """
         opts = self._get_opts(element, x, y)
         opts['count'] = count
@@ -64,14 +64,14 @@ def press(self: T, el: Optional['WebElement'] = None, x: Optional[int] = None,
         """Begin a chain with a press down action at a particular element or point
 
         Args:
-            el (:obj:`appium.webdriver.webelement.WebElement`, optional): the element to press
-            x (:obj:`int`, optional): x coordiate to press. If y is used, x must also be set
-            y (:obj:`int`, optional): y coordiate to press. If x is used, y must also be set
-            pressure (:obj:`float`, optional): [iOS Only] press as force touch. Read the description of `force` property on Apple's UITouch class
+            el: the element to press
+            x: x coordiate to press. If y is used, x must also be set
+            y: y coordiate to press. If x is used, y must also be set
+            pressure: [iOS Only] press as force touch. Read the description of `force` property on Apple's UITouch class
                                 (https://developer.apple.com/documentation/uikit/uitouch?language=objc) for more details on possible value ranges.
 
         Returns:
-            `TouchAction`: self instance
+            `TouchAction`: Self instance
         """
         self._add_action('press', self._get_opts(el, x, y, pressure=pressure))
 
@@ -82,13 +82,13 @@ def long_press(self: T, el: Optional['WebElement'] = None, x: Optional[int]
         """Begin a chain with a press down that lasts `duration` milliseconds
 
         Args:
-            el (:obj:`appium.webdriver.webelement.WebElement`, optional): the element to press
-            x (:obj:`int`, optional): x coordiate to press. If y is used, x must also be set
-            y (:obj:`int`, optional): y coordiate to press. If x is used, y must also be set
-            duration (:obj:`int`, optional): Duration to press
+            el: the element to press
+            x: x coordiate to press. If y is used, x must also be set
+            y: y coordiate to press. If x is used, y must also be set
+            duration: Duration to press
 
         Returns:
-            `TouchAction`: self instance
+            `TouchAction`: Self instance
         """
         self._add_action('longPress', self._get_opts(el, x, y, duration))
 
@@ -98,10 +98,10 @@ def wait(self: T, ms: int = 0) -> T:
         """Pause for `ms` milliseconds.
 
         Args:
-            ms (int): The time to pause
+            ms: The time to pause
 
         Returns:
-            `TouchAction`: self instance
+            `TouchAction`: Self instance
         """
         if ms is None:
             ms = 0
@@ -116,12 +116,12 @@ def move_to(self: T, el: Optional['WebElement'] = None, x: Optional[int] = None,
         """Move the pointer from the previous point to the element or point specified
 
         Args:
-            el (:obj:`appium.webdriver.webelement.WebElement`, optional): the element to be moved to
-            x (:obj:`int`, optional): x coordiate to be moved to. If y is used, x must also be set
-            y (:obj:`int`, optional): y coordiate to be moved to. If x is used, y must also be set
+            el: the element to be moved to
+            x: x coordiate to be moved to. If y is used, x must also be set
+            y: y coordiate to be moved to. If x is used, y must also be set
 
         Returns:
-            `TouchAction`: self instance
+            `TouchAction`: Self instance
         """
         self._add_action('moveTo', self._get_opts(el, x, y))
 
@@ -131,7 +131,7 @@ def release(self: T) -> T:
         """End the action by lifting the pointer off the screen
 
         Returns:
-            `TouchAction`: self instance
+            `TouchAction`: Self instance
         """
         self._add_action('release', {})
 
@@ -141,7 +141,7 @@ def perform(self: T) -> T:
         """Perform the action by sending the commands to the server to be operated upon
 
         Returns:
-            `TouchAction`: self instance
+            `TouchAction`: Self instance
         """
         if self._driver is None:
             raise ValueError('Set driver to constructor as a argument when to create the instance.')

appium/webdriver/extensions/action_helpers.py

@@ -42,7 +42,7 @@ def scroll(self: T, origin_el: WebElement, destination_el: WebElement, duration:
             driver.scroll(el1, el2)
 
         Returns:
-            `appium.webdriver.webelement.WebElement`
+            Union['WebDriver', 'ActionHelpers']: Self instance
         """
 
         # XCUITest x W3C spec has no duration by default in server side
@@ -64,7 +64,7 @@ def drag_and_drop(self: T, origin_el: WebElement, destination_el: WebElement) ->
             destination_el: the element to drag to
 
         Returns:
-            `appium.webdriver.webelement.WebElement`
+            Union['WebDriver', 'ActionHelpers']: Self instance
         """
         action = TouchAction(self)
         action.long_press(origin_el).move_to(destination_el).release().perform()
@@ -75,15 +75,15 @@ def tap(self: T, positions: List[Tuple[int, int]], duration: Optional[int] = Non
         certain time
 
         Args:
-            positions (:obj:`list` of :obj:`tuple`): an array of tuples representing the x/y coordinates of
+            positions: an array of tuples representing the x/y coordinates of
                 the fingers to tap. Length can be up to five.
-            duration (:obj:`int`, optional): length of time to tap, in ms
+            duration: length of time to tap, in ms
 
         Usage:
             driver.tap([(100, 20), (100, 60), (100, 100)], 500)
 
         Returns:
-            `appium.webdriver.webelement.WebElement`
+            Union['WebDriver', 'ActionHelpers']: Self instance
         """
         if len(positions) == 1:
             action = TouchAction(self)
@@ -113,17 +113,17 @@ def swipe(self: T, start_x: int, start_y: int, end_x: int, end_y: int, duration:
         """Swipe from one point to another point, for an optional duration.
 
         Args:
-            start_x (int): x-coordinate at which to start
-            start_y (int): y-coordinate at which to start
-            end_x (int): x-coordinate at which to stop
-            end_y (int): y-coordinate at which to stop
-            duration (:obj:`int`, optional): time to take the swipe, in ms.
+            start_x: x-coordinate at which to start
+            start_y: y-coordinate at which to start
+            end_x: x-coordinate at which to stop
+            end_y: y-coordinate at which to stop
+            duration: time to take the swipe, in ms.
 
         Usage:
             driver.swipe(100, 100, 100, 400)
 
         Returns:
-            `appium.webdriver.webelement.WebElement`
+            Union['WebDriver', 'ActionHelpers']: Self instance
         """
         # `swipe` is something like press-wait-move_to-release, which the server
         # will translate into the correct action
@@ -140,16 +140,16 @@ def flick(self: T, start_x: int, start_y: int, end_x: int, end_y: int) -> T:
         """Flick from one point to another point.
 
         Args:
-            start_x (int): x-coordinate at which to start
-            start_y (int): y-coordinate at which to start
-            end_x (int): x-coordinate at which to stop
-            end_y (int): y-coordinate at which to stop
+            start_x: x-coordinate at which to start
+            start_y: y-coordinate at which to start
+            end_x: x-coordinate at which to stop
+            end_y: y-coordinate at which to stop
 
         Usage:
             driver.flick(100, 100, 100, 400)
 
         Returns:
-            `appium.webdriver.webelement.WebElement`
+            Union['WebDriver', 'ActionHelpers']: Self instance
         """
         action = TouchAction(self)
         action \

appium/webdriver/extensions/android/activities.py

@@ -35,8 +35,8 @@ def start_activity(self: T, app_package: str, app_activity: str, **opts: str) ->
         This is an Android-only method.
 
         Args:
-            app_package (str): The package containing the activity to start.
-            app_activity (str): The activity to start.
+            app_package: The package containing the activity to start.
+            app_activity: The activity to start.
 
         Keyword Args:
             app_wait_package (str): Begin automation after this package starts.
@@ -81,12 +81,12 @@ def wait_activity(self: T, activity: str, timeout: int, interval: int = 1) -> bo
         This is an Android-only method.
 
         Args:
-            activity (str): target activity
-            timeout (int): max wait time, in seconds
-            interval (int): sleep interval between retries, in seconds
+            activity: target activity
+            timeout: max wait time, in seconds
+            interval: sleep interval between retries, in seconds
 
         Returns:
-            bool: `True` if the target activity is shown
+            `True` if the target activity is shown
         """
         try:
             WebDriverWait(self, timeout, interval).until(

appium/webdriver/extensions/android/common.py

@@ -34,8 +34,8 @@ def end_test_coverage(self: T, intent: str, path: str) -> Any:  # TODO Check ret
         See https://github.com/appium/appium/blob/master/docs/en/writing-running-appium/android/android-coverage.md
 
         Args:
-            intent (str): description of operation to be performed
-            path (str): path to coverage.ec file to be pulled from the device
+            intent: description of operation to be performed
+            path: path to coverage.ec file to be pulled from the device
 
         Returns:
             TODO
@@ -50,7 +50,7 @@ def open_notifications(self: T) -> T:
         """Open notification shade in Android (API Level 18 and above)
 
         Returns:
-            `appium.webdriver.webdriver.WebDriver`
+            Union['WebDriver', 'Common']: Self instance
         """
         self.execute(Command.OPEN_NOTIFICATIONS, {})
         return self

appium/webdriver/extensions/android/display.py

@@ -31,10 +31,13 @@ def get_display_density(self: T) -> int:
         """Get the display density, Android only
 
         Returns:
-            int: The display density of the Android device(dpi)
+            The display density of the Android device(dpi)
 
         Usage:
             self.driver.get_display_density()
+
+        Return:
+            int: The display density
         """
         return self.execute(Command.GET_DISPLAY_DENSITY)['value']