From 3b309ea74b0385072af09a8f3f3b28880c210870 Mon Sep 17 00:00:00 2001
From: Johannes Kirschbauer <hsjobeki@gmail.com>
Date: Mon, 7 Jul 2025 15:34:49 +0200
Subject: [PATCH] docs/api: add docstrings to {get_flash_options,
 run_machine_flash}

---
 pkgs/clan-cli/clan_cli/flash/flash.py | 15 +++++++++++++++
 pkgs/clan-cli/clan_cli/flash/list.py  |  6 ++++++
 2 files changed, 21 insertions(+)

diff --git a/pkgs/clan-cli/clan_cli/flash/flash.py b/pkgs/clan-cli/clan_cli/flash/flash.py
index 9f2989ba3..d43ffdd9f 100644
--- a/pkgs/clan-cli/clan_cli/flash/flash.py
+++ b/pkgs/clan-cli/clan_cli/flash/flash.py
@@ -49,6 +49,21 @@ def run_machine_flash(
     extra_args: list[str] | None = None,
     graphical: bool = False,
 ) -> None:
+    """Flash a machine with the given configuration.
+    Args:
+        machine: The Machine instance to flash.
+        mode: The mode to use for flashing (e.g., "install", "reinstall
+        disks: List of Disk instances representing the disks to flash.
+        system_config: SystemConfig instance containing language, keymap, and SSH keys.
+        dry_run: If True, perform a dry run without making changes.
+        write_efi_boot_entries: If True, write EFI boot entries.
+        debug: If True, enable debug mode.
+        extra_args: Additional arguments to pass to the disko-install command.
+        graphical: If True, run the command in graphical mode.
+    Raises:
+        ClanError: If the language or keymap is invalid, or if there are issues with
+            reading SSH keys, or if disko-install fails.
+    """
     devices = [Path(disk.device) for disk in disks]
     with pause_automounting(devices, machine, request_graphical=graphical):
         if extra_args is None:
diff --git a/pkgs/clan-cli/clan_cli/flash/list.py b/pkgs/clan-cli/clan_cli/flash/list.py
index 146f0bcb4..cbcfdace2 100644
--- a/pkgs/clan-cli/clan_cli/flash/list.py
+++ b/pkgs/clan-cli/clan_cli/flash/list.py
@@ -19,6 +19,12 @@ class FlashOptions(TypedDict):
 
 @API.register
 def get_flash_options() -> FlashOptions:
+    """Retrieve available languages and keymaps for flash configuration.
+    Returns:
+        FlashOptions: A dictionary containing lists of available languages and keymaps.
+    Raises:
+        ClanError: If the locale file or keymaps directory does not exist.
+    """
     return {"languages": list_languages(), "keymaps": list_keymaps()}