From ec28c5c3070d5f35faa055940008594959c51d83 Mon Sep 17 00:00:00 2001
From: Johannes Kirschbauer <hsjobeki@gmail.com>
Date: Mon, 7 Jul 2025 15:13:23 +0200
Subject: [PATCH] api/machines: document {get_machine,get_machine_details}

---
 pkgs/clan-cli/clan_lib/machines/actions.py | 13 +++++++++++++
 pkgs/clan-cli/clan_lib/machines/list.py    | 14 ++++++++++++++
 2 files changed, 27 insertions(+)

diff --git a/pkgs/clan-cli/clan_lib/machines/actions.py b/pkgs/clan-cli/clan_lib/machines/actions.py
index 4c19e7a23..93c599a1b 100644
--- a/pkgs/clan-cli/clan_lib/machines/actions.py
+++ b/pkgs/clan-cli/clan_lib/machines/actions.py
@@ -54,6 +54,19 @@ def list_machines(
 
 @API.register
 def get_machine(flake: Flake, name: str) -> InventoryMachine:
+    """
+    Retrieve a machine's inventory details by name from the given flake.
+
+    Args:
+        flake (Flake): The flake object representing the configuration source.
+        name (str): The name of the machine to retrieve from the inventory.
+
+    Returns:
+        InventoryMachine: An instance representing the machine's inventory details.
+
+    Raises:
+        ClanError: If the machine with the specified name is not found in the inventory.
+    """
     inventory_store = InventoryStore(flake=flake)
     inventory = inventory_store.read()
 
diff --git a/pkgs/clan-cli/clan_lib/machines/list.py b/pkgs/clan-cli/clan_lib/machines/list.py
index 0fc152f6e..7fbe4b3ac 100644
--- a/pkgs/clan-cli/clan_lib/machines/list.py
+++ b/pkgs/clan-cli/clan_lib/machines/list.py
@@ -52,8 +52,22 @@ def extract_header(c: str) -> str:
     return "\n".join(header_lines)
 
 
+# TODO: Remove this function
+# Split out the disko schema extraction into a separate function
+# get machine returns the machine already
 @API.register
 def get_machine_details(machine: Machine) -> MachineDetails:
+    """Retrieve detailed information about a machine, including its inventory,
+    hardware configuration, and disk schema if available.
+    Args:
+        machine (Machine): The machine instance for which details are to be retrieved.
+    Returns:
+        MachineDetails: An instance containing the machine's inventory, hardware configuration,
+        and disk schema.
+    Raises:
+        ClanError: If the machine's inventory cannot be found or if there are issues with the
+        hardware configuration or disk schema extraction.
+    """
     machine_inv = get_machine(machine.flake, machine.name)
     hw_config = HardwareConfig.detect_type(machine)