Add doc on configuration code

Signed-off-by: Matthias Beyer <matthias.beyer@atos.net>

6 files changed, 27 insertions, 1 deletions

diff --git a/src/config/configuration.rs b/src/config/configuration.rs
index 4f0e340..aac806c 100644
--- a/src/config/configuration.rs
+++ b/src/config/configuration.rs
@@ -12,6 +12,7 @@ use std::ops::Deref;
 
 use crate::config::NotValidatedConfiguration;
 
+/// A valid configuration (validated via NotValidatedConfiguration::validate())
 #[derive(Debug)]
 pub struct Configuration {
     pub (in crate::config) inner: NotValidatedConfiguration,
diff --git a/src/config/container_config.rs b/src/config/container_config.rs
index a890b8d..a8b3bd6 100644
--- a/src/config/container_config.rs
+++ b/src/config/container_config.rs
@@ -14,11 +14,15 @@ use serde::Deserialize;
 
 use crate::util::EnvironmentVariableName;
 
+/// The configuration for the containers
 #[derive(Debug, CopyGetters, Getters, Deserialize)]
 pub struct ContainerConfig {
+
+    /// check environment names whether they're allowed
     #[getset(get_copy = "pub")]
     check_env_names: bool,
 
+    /// Allowed environment variables (names)
     #[getset(get = "pub")]
     allowed_env: Vec<EnvironmentVariableName>,
 }
diff --git a/src/config/docker_config.rs b/src/config/docker_config.rs
index e427de3..a674e9a 100644
--- a/src/config/docker_config.rs
+++ b/src/config/docker_config.rs
@@ -14,6 +14,7 @@ use serde::Deserialize;
 use crate::config::Endpoint;
 use crate::util::docker::ImageName;
 
+/// Configuration of the docker daemon interfacing functionality
 #[derive(Debug, Getters, CopyGetters, Deserialize)]
 pub struct DockerConfig {
     /// The required docker version
diff --git a/src/config/endpoint_config.rs b/src/config/endpoint_config.rs
index 1ec5e8c..028c86f 100644
--- a/src/config/endpoint_config.rs
+++ b/src/config/endpoint_config.rs
@@ -11,14 +11,18 @@
 use getset::{CopyGetters, Getters};
 use serde::Deserialize;
 
+/// Configuration of a single endpoint
 #[derive(Clone, Debug, Getters, CopyGetters, Deserialize)]
 pub struct Endpoint {
+    /// A human-readable name of the endpoint
     #[getset(get = "pub")]
     name: String,
 
+    /// The URI where the endpoint is reachable
     #[getset(get = "pub")]
     uri: String,
 
+    /// The type of the endpoint
     #[getset(get = "pub")]
     endpoint_type: EndpointType,
 
@@ -35,6 +39,7 @@ pub struct Endpoint {
     maxjobs: usize,
 }
 
+/// The type of an endpoint
 #[derive(Clone, Debug, Deserialize, Eq, PartialEq)]
 pub enum EndpointType {
     #[serde(rename  = "socket")]
diff --git a/src/config/not_validated.rs b/src/config/not_validated.rs
index eab7cbc..36b467b 100644
--- a/src/config/not_validated.rs
+++ b/src/config/not_validated.rs
@@ -21,6 +21,7 @@ use crate::config::DockerConfig;
 use crate::config::util::*;
 use crate::package::PhaseName;
 
+/// The configuration that is loaded from the filesystem
 #[derive(Debug, Getters, Deserialize)]
 pub struct NotValidatedConfiguration {
     #[getset(get = "pub")]
@@ -102,6 +103,11 @@ pub struct NotValidatedConfiguration {
 }
 
 impl NotValidatedConfiguration {
+    /// Validate the NotValidatedConfiguration object and make it into a Configuration object, if
+    /// validation succeeds
+    ///
+    /// This function does sanity-checking on the configuration values.
+    /// It fails with the appropriate error message if a setting is bogus.
     pub fn validate(self) -> Result<Configuration> {
         let crate_version = semver::Version::parse(env!("CARGO_PKG_VERSION"))
             .context("Parsing version of crate (CARGO_PKG_VERSION) into semver::Version object")?;
@@ -110,30 +116,36 @@ impl NotValidatedConfiguration {
             return Err(anyhow!("Configuration is not compatible to butido {}", crate_version))
         }
 
+        // Error if linter is not a file
         if let Some(linter) = self.script_linter.as_ref() {
             if !linter.is_file() {
                 return Err(anyhow!("Lint script is not a file: {}", linter.display()))
             }
         }
 
+        // Error if staging_directory is not a directory
         if !self.staging_directory.is_dir() {
             return Err(anyhow!("Not a directory: staging = {}", self.staging_directory.display()))
         }
 
+        // Error if releases_directory is not a directory
         if !self.releases_directory.is_dir() {
             return Err(anyhow!("Not a directory: releases = {}", self.releases_directory.display()))
         }
 
+        // Error if source_cache_root is not a directory
         if !self.source_cache_root.is_dir() {
             return Err(anyhow!("Not a directory: releases = {}", self.source_cache_root.display()))
         }
 
+        // Error if there are no phases configured
         if self.available_phases.is_empty() {
             return Err(anyhow!("No phases configured"))
         }
 
+        // Error if script highlighting theme is not valid
         if let Some(configured_theme) = self.script_highlight_theme.as_ref() {
-            let allowed_theme_present = [
+            let allowed_theme_present = [ // from syntect
                 "base16-ocean.dark",
                 "base16-eighties.dark",
                 "base16-mocha.dark",
diff --git a/src/config/util.rs b/src/config/util.rs
index 8f251e8..fad9348 100644
--- a/src/config/util.rs
+++ b/src/config/util.rs
@@ -8,6 +8,9 @@
 // SPDX-License-Identifier: EPL-2.0
 //
 
+//! This module contains default functions that are called by serde when deserializing the
+//! configuration and having to use default values.
+
 pub fn default_progress_format() -> String {
     String::from("[{elapsed_precise}] ({percent:>3}%): {bar:40.cyan/blue} | {msg}")
 }