doc: add doc comments to crate

1 files changed, 57 insertions, 0 deletions

diff --git a/src/spec.rs b/src/spec.rs
index 2c13af7..fcf6eab 100644
--- a/src/spec.rs
+++ b/src/spec.rs
@@ -1,3 +1,5 @@
+//! Virtual machine specification.
+
 use crate::config::Configuration;
 
 use log::debug;
@@ -115,62 +117,117 @@ where
     }
 }
 
+/// Effective virtual machine specification.
+///
+/// This is the specification as read from the input file, with the
+/// defaults from the configuration file already applied.
 #[derive(Debug)]
 pub struct Specification {
+    /// Name of new virtual machine to create.
     pub name: String,
+
+    /// SSH public keys to install in the default user's `authorized_keys` file.
     pub ssh_keys: Vec<String>,
+
+    /// RSA host key to install in new VM.
     pub rsa_host_key: Option<String>,
+
+    /// RSA host certificate.
     pub rsa_host_cert: Option<String>,
+
+    /// DSA host key to install in new VM.
     pub dsa_host_key: Option<String>,
+
+    /// DSA host certificate.
     pub dsa_host_cert: Option<String>,
+
+    /// ECDSA host key to install in new VM.
     pub ecdsa_host_key: Option<String>,
+
+    /// ECDSA host certificate.
     pub ecdsa_host_cert: Option<String>,
+
+    /// Ed25519 host key to install in new VM.
     pub ed25519_host_key: Option<String>,
+
+    /// Ed25519 host certificate.
     pub ed25519_host_cert: Option<String>,
 
+    /// Path to base image.
     pub base: PathBuf,
+
+    /// Path to new VM image, to be created.
     pub image: PathBuf,
+
+    /// Size of new image, in GiB.
     pub image_size_gib: u64,
+
+    /// Size of memory for new VM, in MiB.
     pub memory_mib: u64,
+
+    /// CPUs new VM should have.
     pub cpus: u64,
+
+    /// Should a new host key and certificate be created for new VM?
     pub generate_host_certificate: bool,
+
+    /// Path to CA key for creating host certificate.
     pub ca_key: Option<PathBuf>,
 }
 
+/// Errors from this module.
 #[derive(Debug, thiserror::Error)]
 pub enum SpecificationError {
+    /// No base image file specified.
     #[error("No base image or default base image specified for {0}")]
     NoBaseImage(String),
 
+    /// No image file specified.
     #[error("No image filename specified for {0} and no image_directory in configuration")]
     NoImage(String),
 
+    /// No image size specified.
     #[error("No image size specified for {0} and no default configured")]
     NoImageSize(String),
 
+    /// No memory size specified.
     #[error("No memory size specified for {0} and no default configured")]
     NoMemorySize(String),
 
+    /// No CPU count specified.
     #[error("No CPU count specified for {0} and no default configured")]
     NoCpuCount(String),
 
+    /// No SSH authorized keys specified.
     #[error("No SSH authorized keys specified for {0} and no default configured")]
     NoAuthorizedKeys(String),
 
+    /// Error reading SSH public key.
     #[error("Failed to read SSH public key file {0}")]
     SshKeyRead(PathBuf, #[source] std::io::Error),
 
+    /// I/O error.
     #[error(transparent)]
     IoError(#[from] std::io::Error),
 
+    /// Error parsing string as UTF8.
     #[error(transparent)]
     FromUtf8Error(#[from] std::string::FromUtf8Error),
 
+    /// Error parsing YAML.
     #[error(transparent)]
     YamlError(#[from] serde_yaml::Error),
 }
 
 impl Specification {
+    /// Read all specifications from a file.
+    ///
+    /// Apply values from the provided configuration so that the
+    /// returned specifications are *effective* and the caller doesn't
+    /// need to worry about the configuration anymore.
+    ///
+    /// Also, SSH public keys are read from the files named in the
+    /// input specification.
     pub fn from_file(
         config: &Configuration,
         filename: &Path,