api/machines: document {get_machine,get_machine_details}

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()
 

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)