update docstrings

Author: spyoungtech

ahk/_async/engine.py

@@ -147,7 +147,10 @@ def add_hotkey(
         - If you add a hotkey after the hotkey thread/instance is active, it will be restarted automatically
         - `async` functions are not directly supported as callbacks, however you may write a synchronous function that calls `asyncio.run`/`loop.create_task` etc.
 
-        :param hotkey: an instance of ahk.hotkey.Hotkey
+        :param keyname: the key trigger for the hotkey, such as ``#n`` (win+n)
+        :param callback: callback function to call when the hotkey is triggered
+        :param ex_handler: a function which accepts two parameters: the keyname for the hotkey and the exception raised by the callback function.
+        :return:
         """
         hotkey = Hotkey(keyname, callback, ex_handler=ex_handler)
         with warnings.catch_warnings(record=True) as caught_warnings:
@@ -172,7 +175,11 @@ def add_hotstring(
         - You must call the `start_hotkeys` method for registered hotstrings to be active
         - All hotstrings (and hotkeys) run in a single AHK process instance separate from other AHK processes.
 
-        :param hotstring: an instance of ahk.hotkey.Hotstring
+        :param trigger: the trigger phrase for the hotstring, e.g., ``btw``
+        :param replacement_or_callback: the replacement phrase (e.g., ``by the way``) or a Python callable to execute in response to the hotstring trigger
+        :param ex_handler: a function which accepts two parameters: the hotstring and the exception raised by the callback function.
+        :param options: the hotstring options -- same meanings as in AutoHotkey.
+        :return:
         """
         hotstring = Hotstring(trigger, replacement_or_callback, ex_handler=ex_handler, options=options)
         with warnings.catch_warnings(record=True) as caught_warnings:
@@ -269,6 +276,21 @@ async def control_click(
         detect_hidden_windows: Optional[bool] = None,
         blocking: bool = True,
     ) -> Union[None, AsyncFutureResult[None]]:
+        """
+
+        :param button: the mouse button to use
+        :param click_count: how many times to click
+        :param options: options -- same meaning as in AutoHotkey
+        :param control: the control to click
+        :param title:
+        :param text:
+        :param exclude_title:
+        :param exclude_text:
+        :param title_match_mode:
+        :param detect_hidden_windows:
+        :param blocking:
+        :return:
+        """
         args = [control, title, text, str(button), str(click_count), options, exclude_title, exclude_text]
         if detect_hidden_windows is not None:
             if detect_hidden_windows is True:
@@ -325,6 +347,19 @@ async def control_get_text(
         detect_hidden_windows: Optional[bool] = None,
         blocking: bool = True,
     ) -> Union[str, AsyncFutureResult[str]]:
+        """
+        Analog to ``ControlGetText``
+
+        :param control:
+        :param title:
+        :param text:
+        :param exclude_title:
+        :param exclude_text:
+        :param title_match_mode:
+        :param detect_hidden_windows:
+        :param blocking:
+        :return:
+        """
         args = [control, title, text, exclude_title, exclude_text]
         if detect_hidden_windows is not None:
             if detect_hidden_windows is True:
@@ -380,6 +415,19 @@ async def control_get_position(
         detect_hidden_windows: Optional[bool] = None,
         blocking: bool = True,
     ) -> Union[Position, AsyncFutureResult[Position]]:
+        """
+        Analog to ``ControlGetPos``
+
+        :param control:
+        :param title:
+        :param text:
+        :param exclude_title:
+        :param exclude_text:
+        :param title_match_mode:
+        :param detect_hidden_windows:
+        :param blocking:
+        :return:
+        """
         args = [control, title, text, exclude_title, exclude_text]
         if detect_hidden_windows is not None:
             if detect_hidden_windows is True:
@@ -438,7 +486,7 @@ async def control_send(
         blocking: bool = True,
     ) -> Union[None, AsyncFutureResult[None]]:
         """
-        Analog for ControlSend
+        Analog for ``ControlSend``
 
         Reference: https://www.autohotkey.com/docs/commands/ControlSend.htm
 
@@ -582,6 +630,19 @@ async def list_windows(
         detect_hidden_windows: Optional[bool] = None,
         blocking: bool = True,
     ) -> Union[List[AsyncWindow], AsyncFutureResult[List[AsyncWindow]]]:
+        """
+        Enumerate all windows matching the criteria.
+
+
+        :param title:
+        :param text:
+        :param exclude_title:
+        :param exclude_text:
+        :param title_match_mode:
+        :param detect_hidden_windows:
+        :param blocking:
+        :return:
+        """
         args = self._format_win_args(
             title=title,
             text=text,
@@ -606,6 +667,13 @@ async def get_mouse_position(self, coord_mode: Optional[CoordModeRelativeTo] = N
     async def get_mouse_position(
         self, coord_mode: Optional[CoordModeRelativeTo] = None, *, blocking: bool = True
     ) -> Union[Tuple[int, int], AsyncFutureResult[Tuple[int, int]]]:
+        """
+        Analog for ``MouseGetPos``
+
+        :param coord_mode:
+        :param blocking:
+        :return:
+        """
         if coord_mode:
             args = [str(coord_mode)]
         else:
@@ -615,13 +683,24 @@ async def get_mouse_position(
 
     @property
     def mouse_position(self) -> AsyncPropertyReturnTupleIntInt:
+        """
+        Convenience property for ``get_mouse_position``
+
+        :return:
+        """
         warnings.warn(  # unasync: remove
             _PROPERTY_DEPRECATION_WARNING_MESSAGE.format('mouse_position'), category=DeprecationWarning, stacklevel=2
         )
         return self.get_mouse_position()
 
     @mouse_position.setter
     def mouse_position(self, new_position: Tuple[int, int]) -> None:
+        """
+        Convenience setter for ``mouse_move``
+
+        :param new_position: a tuple of x,y coordinates to move to
+        :return:
+        """
         raise RuntimeError('Use of the mouse_position setter is not supported in the async API.')  # unasync: remove
         x, y = new_position
         return self.mouse_move(x=x, y=y, speed=0, relative=False)
@@ -645,6 +724,16 @@ async def mouse_move(
         relative: bool = False,
         blocking: bool = True,
     ) -> Union[None, AsyncFutureResult[None]]:
+        """
+        Analog for ``MouseMove``
+
+        :param x:
+        :param y:
+        :param speed:
+        :param relative:
+        :param blocking:
+        :return:
+        """
         if relative and (x is None or y is None):
             x = x or 0
             y = y or 0
@@ -678,12 +767,23 @@ async def get_active_window(self, blocking: bool = True) -> Union[Optional[Async
     async def get_active_window(
         self, blocking: bool = True
     ) -> Union[Optional[AsyncWindow], AsyncFutureResult[Optional[AsyncWindow]]]:
+        """
+        Gets the currently active window.
+
+        :param blocking:
+        :return:
+        """
         return await self.win_get(
             title='A', detect_hidden_windows=False, title_match_mode=(1, 'Fast'), blocking=blocking
         )
 
     @property
     def active_window(self) -> AsyncPropertyReturnOptionalAsyncWindow:
+        """
+        Gets the currently active window
+
+        :return:
+        """
         warnings.warn(  # unasync: remove
             _PROPERTY_DEPRECATION_WARNING_MESSAGE.format('active_window'), category=DeprecationWarning, stacklevel=2
         )

ahk/_sync/engine.py

@@ -143,7 +143,10 @@ def add_hotkey(
         - If you add a hotkey after the hotkey thread/instance is active, it will be restarted automatically
         - `async` functions are not directly supported as callbacks, however you may write a synchronous function that calls `asyncio.run`/`loop.create_task` etc.
 
-        :param hotkey: an instance of ahk.hotkey.Hotkey
+        :param keyname: the key trigger for the hotkey, such as ``#n`` (win+n)
+        :param callback: callback function to call when the hotkey is triggered
+        :param ex_handler: a function which accepts two parameters: the keyname for the hotkey and the exception raised by the callback function.
+        :return:
         """
         hotkey = Hotkey(keyname, callback, ex_handler=ex_handler)
         with warnings.catch_warnings(record=True) as caught_warnings:
@@ -168,7 +171,11 @@ def add_hotstring(
         - You must call the `start_hotkeys` method for registered hotstrings to be active
         - All hotstrings (and hotkeys) run in a single AHK process instance separate from other AHK processes.
 
-        :param hotstring: an instance of ahk.hotkey.Hotstring
+        :param trigger: the trigger phrase for the hotstring, e.g., ``btw``
+        :param replacement_or_callback: the replacement phrase (e.g., ``by the way``) or a Python callable to execute in response to the hotstring trigger
+        :param ex_handler: a function which accepts two parameters: the hotstring and the exception raised by the callback function.
+        :param options: the hotstring options -- same meanings as in AutoHotkey.
+        :return:
         """
         hotstring = Hotstring(trigger, replacement_or_callback, ex_handler=ex_handler, options=options)
         with warnings.catch_warnings(record=True) as caught_warnings:
@@ -265,6 +272,21 @@ def control_click(
         detect_hidden_windows: Optional[bool] = None,
         blocking: bool = True,
     ) -> Union[None, FutureResult[None]]:
+        """
+
+        :param button: the mouse button to use
+        :param click_count: how many times to click
+        :param options: options -- same meaning as in AutoHotkey
+        :param control: the control to click
+        :param title:
+        :param text:
+        :param exclude_title:
+        :param exclude_text:
+        :param title_match_mode:
+        :param detect_hidden_windows:
+        :param blocking:
+        :return:
+        """
         args = [control, title, text, str(button), str(click_count), options, exclude_title, exclude_text]
         if detect_hidden_windows is not None:
             if detect_hidden_windows is True:
@@ -321,6 +343,19 @@ def control_get_text(
         detect_hidden_windows: Optional[bool] = None,
         blocking: bool = True,
     ) -> Union[str, FutureResult[str]]:
+        """
+        Analog to ``ControlGetText``
+
+        :param control:
+        :param title:
+        :param text:
+        :param exclude_title:
+        :param exclude_text:
+        :param title_match_mode:
+        :param detect_hidden_windows:
+        :param blocking:
+        :return:
+        """
         args = [control, title, text, exclude_title, exclude_text]
         if detect_hidden_windows is not None:
             if detect_hidden_windows is True:
@@ -376,6 +411,19 @@ def control_get_position(
         detect_hidden_windows: Optional[bool] = None,
         blocking: bool = True,
     ) -> Union[Position, FutureResult[Position]]:
+        """
+        Analog to ``ControlGetPos``
+
+        :param control:
+        :param title:
+        :param text:
+        :param exclude_title:
+        :param exclude_text:
+        :param title_match_mode:
+        :param detect_hidden_windows:
+        :param blocking:
+        :return:
+        """
         args = [control, title, text, exclude_title, exclude_text]
         if detect_hidden_windows is not None:
             if detect_hidden_windows is True:
@@ -434,7 +482,7 @@ def control_send(
         blocking: bool = True,
     ) -> Union[None, FutureResult[None]]:
         """
-        Analog for ControlSend
+        Analog for ``ControlSend``
 
         Reference: https://www.autohotkey.com/docs/commands/ControlSend.htm
 
@@ -578,6 +626,19 @@ def list_windows(
         detect_hidden_windows: Optional[bool] = None,
         blocking: bool = True,
     ) -> Union[List[Window], FutureResult[List[Window]]]:
+        """
+        Enumerate all windows matching the criteria.
+
+
+        :param title:
+        :param text:
+        :param exclude_title:
+        :param exclude_text:
+        :param title_match_mode:
+        :param detect_hidden_windows:
+        :param blocking:
+        :return:
+        """
         args = self._format_win_args(
             title=title,
             text=text,
@@ -602,6 +663,13 @@ def get_mouse_position(self, coord_mode: Optional[CoordModeRelativeTo] = None, *
     def get_mouse_position(
         self, coord_mode: Optional[CoordModeRelativeTo] = None, *, blocking: bool = True
     ) -> Union[Tuple[int, int], FutureResult[Tuple[int, int]]]:
+        """
+        Analog for ``MouseGetPos``
+
+        :param coord_mode:
+        :param blocking:
+        :return:
+        """
         if coord_mode:
             args = [str(coord_mode)]
         else:
@@ -611,10 +679,21 @@ def get_mouse_position(
 
     @property
     def mouse_position(self) -> SyncPropertyReturnTupleIntInt:
+        """
+        Convenience property for ``get_mouse_position``
+
+        :return:
+        """
         return self.get_mouse_position()
 
     @mouse_position.setter
     def mouse_position(self, new_position: Tuple[int, int]) -> None:
+        """
+        Convenience setter for ``mouse_move``
+
+        :param new_position: a tuple of x,y coordinates to move to
+        :return:
+        """
         x, y = new_position
         return self.mouse_move(x=x, y=y, speed=0, relative=False)
 
@@ -637,6 +716,16 @@ def mouse_move(
         relative: bool = False,
         blocking: bool = True,
     ) -> Union[None, FutureResult[None]]:
+        """
+        Analog for ``MouseMove``
+
+        :param x:
+        :param y:
+        :param speed:
+        :param relative:
+        :param blocking:
+        :return:
+        """
         if relative and (x is None or y is None):
             x = x or 0
             y = y or 0
@@ -670,12 +759,23 @@ def get_active_window(self, blocking: bool = True) -> Union[Optional[Window], Fu
     def get_active_window(
         self, blocking: bool = True
     ) -> Union[Optional[Window], FutureResult[Optional[Window]]]:
+        """
+        Gets the currently active window.
+
+        :param blocking:
+        :return:
+        """
         return self.win_get(
             title='A', detect_hidden_windows=False, title_match_mode=(1, 'Fast'), blocking=blocking
         )
 
     @property
     def active_window(self) -> SyncPropertyReturnOptionalAsyncWindow:
+        """
+        Gets the currently active window
+
+        :return:
+        """
         return self.get_active_window()
 
     def find_windows(