From 4a8106660c52e6838e10ac8de12de4ea144446e8 Mon Sep 17 00:00:00 2001
From: ryan <ryan@distrust.co>
Date: Fri, 9 May 2025 14:19:31 -0400
Subject: [PATCH] add more documentation

---
 src/cli.rs |  2 +-
 src/vm.rs  | 17 +++++++++++++++++
 2 files changed, 18 insertions(+), 1 deletion(-)

diff --git a/src/cli.rs b/src/cli.rs
index ab08771..6f25e91 100644
--- a/src/cli.rs
+++ b/src/cli.rs
@@ -32,7 +32,7 @@ pub enum Commands {
 
     /// Attach a USB device to a running VM.
     Attach {
-        /// The device to attach.
+        /// The device to attach, in the format of `vendorid:deviceid`.
         device: DeviceIdentifier,
     },
 
diff --git a/src/vm.rs b/src/vm.rs
index d060d10..70f36d7 100644
--- a/src/vm.rs
+++ b/src/vm.rs
@@ -117,6 +117,8 @@ fn find_pci_device_by_class(class: u16) -> Result<Vec<Device>> {
 }
 
 // NOTE: Do not implement `clone`, as there is side-effect state involved.
+
+/// A control handle for a virtual machine.
 #[derive(Debug)]
 pub struct VirtualMachine {
     pid: u32,
@@ -163,6 +165,7 @@ impl Default for SpawnArguments {
 }
 
 impl VirtualMachine {
+    /// Start a virutal machine with the given parameters.
     pub fn start(args: SpawnArguments) -> eyre::Result<Self> {
         let eth_devices = find_pci_device_by_class(0x0200)?;
 
@@ -274,6 +277,10 @@ impl VirtualMachine {
         Self::load(args, Some(child.id()))
     }
 
+    /// Load a virtual machine with the given parameters and optionally a custom PID.
+    ///
+    /// The custom PID option may be relevant if the virtual machine sockets were loaded but the
+    /// PID of the virtual machine was not properly persisted.
     pub fn load(args: SpawnArguments, pid: Option<u32>) -> Result<Self> {
         let bar = spinner("Connecting to VM");
         let pid = if let Some(pid) = pid {
@@ -356,6 +363,7 @@ impl VirtualMachine {
         Ok(vm)
     }
 
+    /// The PID of the virtual machine.
     pub fn pid(&self) -> u32 {
         self.pid
     }
@@ -391,6 +399,7 @@ impl VirtualMachine {
         Ok(())
     }
 
+    /// Push a single file from the local machine to the VM.
     pub fn push(
         &mut self,
         local_path: impl AsRef<Path>,
@@ -460,6 +469,8 @@ impl VirtualMachine {
         Ok(())
     }
 
+    /// Pull a single file from the VM to the local machine. This operation is destructive and will
+    /// overwrite existing files.
     pub fn pull(
         &mut self,
         remote_path: impl AsRef<Path>,
@@ -557,6 +568,8 @@ impl VirtualMachine {
 
     // TODO: make this return status, stdout, stderr
     // TODO: accept optional: env, input-data, disable capture-output
+    /// Run a command on the virtual machine. Standard input is not sent to the process, and only
+    /// standard output is received from the process.
     pub fn run_command(
         &mut self,
         command: &str,
@@ -643,6 +656,7 @@ impl VirtualMachine {
         }
     }
 
+    /// Execute an operation via QEMU Guest Agent. This modifies state inside the VM.
     pub fn execute<S: serde::Serialize + Debug>(
         &mut self,
         command: &'static str,
@@ -654,6 +668,8 @@ impl VirtualMachine {
         result
     }
 
+    /// Execute an operation via QEMU Machine Protocol. This modifies state on the host machine and
+    /// the VM.
     pub fn execute_host<S: serde::Serialize + Debug>(
         &mut self,
         command: &'static str,
@@ -692,6 +708,7 @@ impl VirtualMachine {
     // NOTE: u32 is returned from Process::id(), i32 is the Linux internal version
     // This should be safe; the kernel wouldn't give a value that, when converted
     // to a u32, can't be made back into an i32
+    /// Terminate the VM and remove any stateful files.
     pub fn kill(self) -> Result<()> {
         use nix::{
             errno::Errno,