Add docstrings to Windows console wrapper functions

Author: darrenburns

rich/_win32_console.py

@@ -40,6 +40,15 @@ class WindowsCoordinates(NamedTuple):
 
     @classmethod
     def from_param(cls, value: "WindowsCoordinates") -> COORD:
+        """Converts a WindowsCoordinates into a wintypes _COORD structure.
+        This classmethod is internally called by ctypes to perform the conversion.
+
+        Args:
+            value (WindowsCoordinates): The input coordinates to convert.
+
+        Returns:
+            wintypes._COORD: The converted coordinates struct.
+        """
         return COORD(value.col, value.row)
 
 
@@ -65,6 +74,14 @@ class CONSOLE_CURSOR_INFO(ctypes.Structure):
 
 
 def GetStdHandle(handle: int = STDOUT) -> wintypes.HANDLE:
+    """Retrieves a handle to the specified standard device (standard input, standard output, or standard error).
+
+    Args:
+        handle (int): Integer identifier for the handle. Defaults to -11 (stdout).
+
+    Returns:
+        wintypes.HANDLE: The handle
+    """
     return cast(wintypes.HANDLE, _GetStdHandle(handle))
 
 
@@ -74,6 +91,20 @@ def GetStdHandle(handle: int = STDOUT) -> wintypes.HANDLE:
 
 
 def GetConsoleMode(std_handle: wintypes.HANDLE) -> int:
+    """Retrieves the current input mode of a console's input buffer
+    or the current output mode of a console screen buffer.
+
+    Args:
+        std_handle (wintypes.HANDLE): A handle to the console input buffer or the console screen buffer.
+
+    Raises:
+        LegacyWindowsError: If any error occurs while calling the Windows console API.
+
+    Returns:
+        int: Value representing the current console mode as documented at
+            https://docs.microsoft.com/en-us/windows/console/getconsolemode#parameters
+    """
+
     console_mode = wintypes.DWORD()
     success = bool(_GetConsoleMode(std_handle, console_mode))
     if not success:
@@ -98,8 +129,17 @@ def FillConsoleOutputCharacter(
     length: int,
     start: WindowsCoordinates,
 ) -> int:
-    """Writes a character to the console screen buffer a specified number of times, beginning at the specified coordinates."""
-    assert len(char) == 1
+    """Writes a character to the console screen buffer a specified number of times, beginning at the specified coordinates.
+
+    Args:
+        std_handle (wintypes.HANDLE): A handle to the console input buffer or the console screen buffer.
+        char (str): The character to write. Must be a string of length 1.
+        length (int): The number of times to write the character.
+        start (WindowsCoordinates): The coordinates to start writing at.
+
+    Returns:
+        int: The number of characters written.
+    """
     character = ctypes.c_char(char.encode())
     num_characters = wintypes.DWORD(length)
     num_written = wintypes.DWORD(0)
@@ -130,6 +170,18 @@ def FillConsoleOutputAttribute(
     length: int,
     start: WindowsCoordinates,
 ) -> int:
+    """Sets the character attributes for a specified number of character cells,
+    beginning at the specified coordinates in a screen buffer.
+
+    Args:
+        std_handle (wintypes.HANDLE): A handle to the console input buffer or the console screen buffer.
+        attributes (int): Integer value representing the foreground and background colours of the cells.
+        length (int): The number of cells to set the output attribute of.
+        start (WindowsCoordinates): The coordinates of the first cell whose attributes are to be set.
+
+    Returns:
+        int: The number of cells whose attributes were actually set.
+    """
     num_cells = wintypes.DWORD(length)
     style_attrs = wintypes.WORD(attributes)
     num_written = wintypes.DWORD(0)
@@ -150,6 +202,16 @@ def FillConsoleOutputAttribute(
 def SetConsoleTextAttribute(
     std_handle: wintypes.HANDLE, attributes: wintypes.WORD
 ) -> bool:
+    """Set the colour attributes for all text written after this function is called.
+
+    Args:
+        std_handle (wintypes.HANDLE): A handle to the console input buffer or the console screen buffer.
+        attributes (int): Integer value representing the foreground and background colours.
+
+
+    Returns:
+        bool: True if the attribute was set successfully, otherwise False.
+    """
     return bool(_SetConsoleTextAttribute(std_handle, attributes))
 
 
@@ -164,6 +226,14 @@ def SetConsoleTextAttribute(
 def GetConsoleScreenBufferInfo(
     std_handle: wintypes.HANDLE,
 ) -> CONSOLE_SCREEN_BUFFER_INFO:
+    """Retrieves information about the specified console screen buffer.
+
+    Args:
+        std_handle (wintypes.HANDLE): A handle to the console input buffer or the console screen buffer.
+
+    Returns:
+        CONSOLE_SCREEN_BUFFER_INFO: A CONSOLE_SCREEN_BUFFER_INFO ctype struct contain information about
+            screen size, cursor position, colour attributes, and more."""
     console_screen_buffer_info = CONSOLE_SCREEN_BUFFER_INFO()
     _GetConsoleScreenBufferInfo(std_handle, byref(console_screen_buffer_info))
     return console_screen_buffer_info
@@ -180,6 +250,15 @@ def GetConsoleScreenBufferInfo(
 def SetConsoleCursorPosition(
     std_handle: wintypes.HANDLE, coords: WindowsCoordinates
 ) -> bool:
+    """Set the position of the cursor in the console screen
+
+    Args:
+        std_handle (wintypes.HANDLE): A handle to the console input buffer or the console screen buffer.
+        coords (WindowsCoordinates): The coordinates to move the cursor to.
+
+    Returns:
+        bool: True if the function succeeds, otherwise False.
+    """
     return bool(_SetConsoleCursorPosition(std_handle, coords))
 
 
@@ -194,6 +273,15 @@ def SetConsoleCursorPosition(
 def SetConsoleCursorInfo(
     std_handle: wintypes.HANDLE, cursor_info: CONSOLE_CURSOR_INFO
 ) -> bool:
+    """Set the cursor info - used for adjusting cursor visibility and width
+
+    Args:
+        std_handle (wintypes.HANDLE): A handle to the console input buffer or the console screen buffer.
+        cursor_info (CONSOLE_CURSOR_INFO): CONSOLE_CURSOR_INFO ctype struct containing the new cursor info.
+
+    Returns:
+          bool: True if the function succeeds, otherwise False.
+    """
     return bool(_SetConsoleCursorInfo(std_handle, byref(cursor_info)))
 
 
@@ -203,6 +291,14 @@ def SetConsoleCursorInfo(
 
 
 def SetConsoleTitle(title: str) -> bool:
+    """Sets the title of the current console window
+
+    Args:
+        title (str): The new title of the console window.
+
+    Returns:
+        bool: True if the function succeeds, otherwise False.
+    """
     return bool(_SetConsoleTitle(title))
 
 
@@ -218,6 +314,15 @@ def SetConsoleTitle(title: str) -> bool:
 
 
 def WriteConsole(std_handle: wintypes.HANDLE, text: str) -> bool:
+    """Write a string of text to the console, starting at the current cursor position
+
+    Args:
+        std_handle (wintypes.HANDLE): A handle to the console input buffer or the console screen buffer.
+        text (str): The text to write.
+
+    Returns:
+        bool: True if the function succeeds, otherwise False.
+    """
     buffer = wintypes.LPWSTR(text)
     num_chars_written = wintypes.LPDWORD()
     return bool(