doc: add doc comments to crate

5 files changed, 41 insertions, 0 deletions

diff --git a/src/cmd/cloud_init.rs b/src/cmd/cloud_init.rs
index a9b3588..b266eb4 100644
--- a/src/cmd/cloud_init.rs
+++ b/src/cmd/cloud_init.rs
@@ -1,17 +1,27 @@
+//! The `cloud-init` sub-command.
+
 use crate::cloudinit::{CloudInitConfig, CloudInitError};
 use crate::spec::Specification;
 use log::{debug, info};
 use std::path::Path;
 
+/// Errors from this module.
 #[derive(Debug, thiserror::Error)]
 pub enum CloudInitCommandError {
+    /// Error in the cloud-init configuration.
     #[error(transparent)]
     CloudInitError(#[from] CloudInitError),
 
+    /// Error doing I/O.
     #[error(transparent)]
     IoError(#[from] std::io::Error),
 }
 
+/// The `cloud-init` sub-command.
+///
+/// This sub-command generates the cloud-init configuration based on
+/// specifications provided by the caller and writes them to files in
+/// a directory named by the caller.
 pub fn cloud_init(specs: &[Specification], dirname: &Path) -> Result<(), CloudInitCommandError> {
     for spec in specs {
         let dirname = dirname.join(&spec.name);
diff --git a/src/cmd/delete.rs b/src/cmd/delete.rs
index 3f60e27..a9a0660 100644
--- a/src/cmd/delete.rs
+++ b/src/cmd/delete.rs
@@ -1,18 +1,26 @@
+//! The `delete` sub-command.
+
 use crate::spec::Specification;
 use log::{debug, info};
 use std::thread;
 use std::time::Duration;
 use virt::connect::Connect;
 
+/// Errors from this module.
 #[derive(Debug, thiserror::Error)]
 pub enum DeleteError {
+    /// Error creating virtual machine.
     #[error(transparent)]
     VirtError(#[from] virt::error::Error),
 
+    /// Error doing I/O.
     #[error(transparent)]
     IoError(#[from] std::io::Error),
 }
 
+/// Delete VMs corresponding to specifications.
+///
+/// Delete the VM corresponding to each specification provided by the caller.
 pub fn delete(specs: &[Specification]) -> Result<(), DeleteError> {
     for spec in specs {
         info!("deleting virtual machine {}", spec.name);
diff --git a/src/cmd/list.rs b/src/cmd/list.rs
index a67dfb7..c83be26 100644
--- a/src/cmd/list.rs
+++ b/src/cmd/list.rs
@@ -1,13 +1,21 @@
+//! The `list` sub-command.
+
 use crate::config::Configuration;
 
 use virt::connect::Connect;
 
+/// Errors returned from this module.
 #[derive(Debug, thiserror::Error)]
 pub enum ListError {
+    /// An error from libvirt.
     #[error(transparent)]
     VirtError(#[from] virt::error::Error),
 }
 
+/// The `list` sub-command.
+///
+/// Return all the virtual machines existing on the libvirt instance,
+/// and their current state.
 pub fn list(_config: &Configuration) -> Result<(), ListError> {
     let conn = Connect::open("qemu:///system")?;
     let domains = conn.list_all_domains(0)?;
diff --git a/src/cmd/mod.rs b/src/cmd/mod.rs
index f1e029c..606e326 100644
--- a/src/cmd/mod.rs
+++ b/src/cmd/mod.rs
@@ -1,3 +1,8 @@
+//! Implementations of command line sub-commands.
+//!
+//! This module has sub-modules with functions for all the
+//! sub-commands of the command line tool part of the crate.
+
 pub mod new;
 pub use new::new;
 
diff --git a/src/cmd/new.rs b/src/cmd/new.rs
index 0f7bc94..57f69ae 100644
--- a/src/cmd/new.rs
+++ b/src/cmd/new.rs
@@ -1,3 +1,5 @@
+//! The `new` sub-command.
+
 use crate::cloudinit::{CloudInitConfig, CloudInitError};
 use crate::image::{ImageError, VirtualMachineImage};
 use crate::install::{virt_install, VirtInstallArgs, VirtInstallError};
@@ -9,18 +11,26 @@ use std::net::TcpStream;
 
 const SSH_PORT: i32 = 22;
 
+/// Errors returned by this module.
 #[derive(Debug, thiserror::Error)]
 pub enum NewError {
+    /// Problem with cloud-init configuration.
     #[error(transparent)]
     CloudInitError(#[from] CloudInitError),
 
+    /// Problem creating VM image.
     #[error(transparent)]
     ImageError(#[from] ImageError),
 
+    /// Problem with libvirt.
     #[error(transparent)]
     VirtInstallError(#[from] VirtInstallError),
 }
 
+/// The `new` sub-command.
+///
+/// Create all the new virtual machines specified by the caller. Wait
+/// until each VM's SSH port listens for connections.
 pub fn new(specs: &[Specification]) -> Result<(), NewError> {
     for spec in specs {
         info!("creating new VM {}", spec.name);