doc: add doc comments to crate

1 files changed, 27 insertions, 0 deletions

diff --git a/src/cloudinit.rs b/src/cloudinit.rs
index ccf98eb..ec4efd3 100644
--- a/src/cloudinit.rs
+++ b/src/cloudinit.rs
@@ -1,3 +1,10 @@
+//! Prepare [cloud-init][] configuration.
+//!
+//! The configuration is provided to cloud-init via the "NoCloud"
+//! route, using an ISO image file.
+//!
+//! [cloud-init]: https://cloud-init.io/
+
 use crate::spec::{Specification, SpecificationError};
 use crate::sshkeys::{CaKey, KeyError, KeyKind, KeyPair};
 use log::debug;
@@ -92,26 +99,34 @@ log("vmadm cloud-init script ending")
 logfile.close()
 "#;
 
+/// Errors from this module.
 #[derive(Debug, thiserror::Error)]
 pub enum CloudInitError {
+    /// CA key is not specified.
     #[error("Host certificate requested, but no CA key specified")]
     NoCAKey,
 
+    /// Something went wrong creating ISO image with configuration.
     #[error("failed to create ISO image with genisoimage: {0}")]
     IsoFailed(String),
 
+    /// Error in the specification.
     #[error(transparent)]
     SpecificationError(#[from] SpecificationError),
 
+    /// Error in generating SSH host key or certificate.
     #[error(transparent)]
     KeyError(#[from] KeyError),
 
+    /// Something went wrong doing I/O.
     #[error(transparent)]
     IoError(#[from] std::io::Error),
 
+    /// Something went wrong parsing a string as UTF8.
     #[error(transparent)]
     StringError(#[from] std::string::FromUtf8Error),
 
+    /// Something went wrong parsing or serializing to YAML.
     #[error(transparent)]
     SerdeError(#[from] serde_yaml::Error),
 }
@@ -252,6 +267,7 @@ impl Hostkeys {
     }
 }
 
+/// Full cloud-init configuration.
 #[derive(Clone, Debug)]
 pub struct CloudInitConfig {
     metadata: Metadata,
@@ -259,12 +275,14 @@ pub struct CloudInitConfig {
 }
 
 impl CloudInitConfig {
+    /// Create from a specification.
     pub fn from(spec: &Specification) -> Result<Self, CloudInitError> {
         let metadata = Metadata::from(spec);
         let userdata = Userdata::from(spec)?;
         Ok(CloudInitConfig { metadata, userdata })
     }
 
+    /// Debugging aid: dump cloud-init to stdout.
     pub fn dump(&self) {
         println!("==== meta-data:\n{}", self.metadata().unwrap());
         println!("==== user-data:\n{}", self.userdata().unwrap());
@@ -278,6 +296,11 @@ impl CloudInitConfig {
         Ok(self.userdata.as_yaml()?)
     }
 
+    /// Put cloud-init configuration into a named directory.
+    ///
+    /// The files `meta-data` and `user-data` will be stored in the
+    /// directory. cloud-init reads them on first boot and makes
+    /// appropriate changes the host's configuration.
     pub fn create_dir(&self, path: &Path) -> Result<(), CloudInitError> {
         let metadata = path.join("meta-data");
         debug!("writing metadata to {}", metadata.display());
@@ -300,6 +323,10 @@ impl CloudInitConfig {
         Ok(())
     }
 
+    /// Create an ISO disk image file with the cloud-init configuration.
+    ///
+    /// The image will be attached to the VM when it starts.
+    /// cloud-init finds it via the volume ID (file system label).
     pub fn create_iso(&self, filename: &Path) -> Result<(), CloudInitError> {
         let dir = tempdir()?;
         self.create_dir(dir.path())?;