add docstrings

openadapt/window/_windows.py

@@ -6,53 +6,95 @@
 import pickle
 
 
-def get_active_window_state():
+def get_active_window_state() -> dict:
+    """
+    Get the state of the active window.
+
+    Returns:
+        dict: A dictionary containing the state of the active window.
+            The dictionary has the following keys:
+                - "title": Title of the active window.
+                - "left": Left position of the active window.
+                - "top": Top position of the active window.
+                - "width": Width of the active window.
+                - "height": Height of the active window.
+                - "meta": Meta information of the active window.
+                - "data": None (to be filled with window data).
+                - "window_id": ID of the active window.
+    """
     active_window = get_active_window()
     meta = get_active_window_meta(active_window)
-    data = get_window_data(active_window)
+    data = get_descendants_info(active_window)
     state = {
         "title": meta["texts"][0],
         "left": meta["rectangle"].left,
         "top": meta["rectangle"].top,
         "width": meta["rectangle"].width(),
         "height": meta["rectangle"].height(),
         "meta": meta,
-        "data": None,
+        "data": data,
         "window_id": meta["control_id"],
     }
     return state
 
 
-def get_active_window_meta(active_window):
+def get_active_window_meta(active_window) -> dict:
+    """
+    Get the meta information of the active window.
+
+    Args:
+        active_window: The active window object.
+
+    Returns:
+        dict: A dictionary containing the meta information of the active window.
+    """
     if not active_window:
         logger.warning(f"{active_window=}")
         return None
     logger.info(f"{active_window.get_properties()}=")
     return active_window.get_properties()
 
 
-def get_active_element_state(x, y):
+def get_active_element_state(x: int, y: int):
+    """
+    Get the state of the active element at the given coordinates.
+
+    Args:
+        x (int): The x-coordinate.
+        y (int): The y-coordinate.
+
+    Returns:
+        dict: A dictionary containing the properties of the active element.
+    """
     active_window = get_active_window()
     active_element = active_window.from_point(x, y)
     properties = active_element.get_properties()
     return properties
 
 
-def get_active_window():
+def get_active_window() -> Desktop:
+    """
+    Get the active window object.
+
+    Returns:
+        Desktop: The active window object.
+    """
     app = pywinauto.application.Application(backend="uia").connect(active_only=True)
     window = app.active()
     logger.info(f"{window=}")
     return window
 
 
-def get_window_data(active_window):
-    state = get_descendants_info(active_window)
-    logger.info(f"{state=}")
-    # state = window.dump_window()
-    return state
+def get_descendants_info(window):
+    """
+    Get the properties of the descendants of the given window.
 
+    Args:
+        window: The window object.
 
-def get_descendants_info(window):
+    Returns:
+        list: A list containing the properties of the descendants.
+    """
     result = []
     for child in window.descendants():
         info = child.get_properties()