Merge branch 'doc'

18 files changed, 85 insertions, 1 deletions

diff --git a/src/commands/build.rs b/src/commands/build.rs
index df4b672..8825750 100644
--- a/src/commands/build.rs
+++ b/src/commands/build.rs
@@ -8,6 +8,8 @@
 // SPDX-License-Identifier: EPL-2.0
 //
 
+//! Implementation of the 'build' subcommand
+
 use std::io::Write;
 use std::path::Path;
 use std::path::PathBuf;
diff --git a/src/commands/db.rs b/src/commands/db.rs
index 09cd67d..2481259 100644
--- a/src/commands/db.rs
+++ b/src/commands/db.rs
@@ -8,6 +8,8 @@
 // SPDX-License-Identifier: EPL-2.0
 //
 
+//! Implementation of the 'db' subcommand
+
 use std::io::Write;
 use std::path::PathBuf;
 use std::process::Command;
@@ -56,6 +58,7 @@ pub fn db(
     }
 }
 
+/// Implementation of the "db cli" subcommand
 fn cli(db_connection_config: DbConnectionConfig<'_>, matches: &ArgMatches) -> Result<()> {
     trait PgCliCommand {
         fn run_for_uri(&self, dbcc: DbConnectionConfig<'_>) -> Result<()>;
@@ -139,6 +142,7 @@ fn cli(db_connection_config: DbConnectionConfig<'_>, matches: &ArgMatches) -> Re
         .run_for_uri(db_connection_config)
 }
 
+/// Implementation of the "db artifacts" subcommand
 fn artifacts(conn_cfg: DbConnectionConfig<'_>, matches: &ArgMatches) -> Result<()> {
     use crate::schema::artifacts::dsl;
 
@@ -188,6 +192,7 @@ fn artifacts(conn_cfg: DbConnectionConfig<'_>, matches: &ArgMatches) -> Result<(
     Ok(())
 }
 
+/// Implementation of the "db envvars" subcommand
 fn envvars(conn_cfg: DbConnectionConfig<'_>, matches: &ArgMatches) -> Result<()> {
     use crate::schema::envvars::dsl;
 
@@ -209,6 +214,7 @@ fn envvars(conn_cfg: DbConnectionConfig<'_>, matches: &ArgMatches) -> Result<()>
     Ok(())
 }
 
+/// Implementation of the "db images" subcommand
 fn images(conn_cfg: DbConnectionConfig<'_>, matches: &ArgMatches) -> Result<()> {
     use crate::schema::images::dsl;
 
@@ -230,6 +236,7 @@ fn images(conn_cfg: DbConnectionConfig<'_>, matches: &ArgMatches) -> Result<()>
     Ok(())
 }
 
+/// Implementation of the "db submit" subcommand
 fn submit(conn_cfg: DbConnectionConfig<'_>, matches: &ArgMatches) -> Result<()> {
     let conn = conn_cfg.establish_connection()?;
     let submit_id = matches.value_of("submit")
@@ -300,6 +307,7 @@ fn submit(conn_cfg: DbConnectionConfig<'_>, matches: &ArgMatches) -> Result<()>
     crate::commands::util::display_data(header, data, false)
 }
 
+/// Implementation of the "db submits" subcommand
 fn submits(conn_cfg: DbConnectionConfig<'_>, matches: &ArgMatches) -> Result<()> {
     let csv = matches.is_present("csv");
     let limit = matches.value_of("limit").map(i64::from_str).transpose()?;
@@ -366,6 +374,7 @@ fn submits(conn_cfg: DbConnectionConfig<'_>, matches: &ArgMatches) -> Result<()>
     Ok(())
 }
 
+/// Implementation of the "db jobs" subcommand
 fn jobs(conn_cfg: DbConnectionConfig<'_>, matches: &ArgMatches) -> Result<()> {
     let csv = matches.is_present("csv");
     let hdrs = crate::commands::util::mk_header(vec![
@@ -457,6 +466,7 @@ fn jobs(conn_cfg: DbConnectionConfig<'_>, matches: &ArgMatches) -> Result<()> {
     Ok(())
 }
 
+/// Implementation of the "db job" subcommand
 fn job(conn_cfg: DbConnectionConfig<'_>, config: &Configuration, matches: &ArgMatches) -> Result<()> {
     let script_highlight = !matches.is_present("no_script_highlight");
     let script_line_numbers = !matches.is_present("no_script_line_numbers");
@@ -650,6 +660,7 @@ fn log_of(conn_cfg: DbConnectionConfig<'_>, matches: &ArgMatches) -> Result<()>
         .map(|_| ())
 }
 
+/// Implementation of the "db releases" subcommand
 fn releases(conn_cfg: DbConnectionConfig<'_>, config: &Configuration, matches: &ArgMatches) -> Result<()> {
     let csv    = matches.is_present("csv");
     let conn   = conn_cfg.establish_connection()?;
diff --git a/src/commands/dependencies_of.rs b/src/commands/dependencies_of.rs
index 41a8531..3e4ff21 100644
--- a/src/commands/dependencies_of.rs
+++ b/src/commands/dependencies_of.rs
@@ -8,6 +8,8 @@
 // SPDX-License-Identifier: EPL-2.0
 //
 
+//! Implementation of the 'dependencies-of' subcommand
+
 use anyhow::Result;
 use clap::ArgMatches;
 use log::trace;
diff --git a/src/commands/endpoint.rs b/src/commands/endpoint.rs
index 023fd74..4de51d2 100644
--- a/src/commands/endpoint.rs
+++ b/src/commands/endpoint.rs
@@ -8,6 +8,8 @@
 // SPDX-License-Identifier: EPL-2.0
 //
 
+//! Implementation of the 'endpoint' subcommand
+
 use std::collections::HashMap;
 use std::ops::Deref;
 use std::str::FromStr;
diff --git a/src/commands/endpoint_container.rs b/src/commands/endpoint_container.rs
index abaf49e..9ee3f3b 100644
--- a/src/commands/endpoint_container.rs
+++ b/src/commands/endpoint_container.rs
@@ -8,6 +8,8 @@
 // SPDX-License-Identifier: EPL-2.0
 //
 
+//! Implementation of the 'endpoint container' subcommand
+
 use std::str::FromStr;
 
 use anyhow::Error;
diff --git a/src/commands/env_of.rs b/src/commands/env_of.rs
index c763a23..9eebc28 100644
--- a/src/commands/env_of.rs
+++ b/src/commands/env_of.rs
@@ -8,6 +8,8 @@
 // SPDX-License-Identifier: EPL-2.0
 //
 
+//! Implementation of the 'env-of' subcommand
+
 use std::convert::TryFrom;
 
 use anyhow::Result;
diff --git a/src/commands/find_artifact.rs b/src/commands/find_artifact.rs
index 17db563..19e8e2f 100644
--- a/src/commands/find_artifact.rs
+++ b/src/commands/find_artifact.rs
@@ -8,6 +8,8 @@
 // SPDX-License-Identifier: EPL-2.0
 //
 
+//! Implementation of the 'find-artifact' subcommand
+
 use std::path::PathBuf;
 use std::io::Write;
 use std::sync::Arc;
diff --git a/src/commands/find_pkg.rs b/src/commands/find_pkg.rs
index 7190ef8..d45c946 100644
--- a/src/commands/find_pkg.rs
+++ b/src/commands/find_pkg.rs
@@ -8,6 +8,8 @@
 // SPDX-License-Identifier: EPL-2.0
 //
 
+//! Implementation of the 'find-pkg' subcommand
+
 use std::convert::TryFrom;
 
 use anyhow::Context;
diff --git a/src/commands/lint.rs b/src/commands/lint.rs
index 2a54c62..951b845 100644
--- a/src/commands/lint.rs
+++ b/src/commands/lint.rs
@@ -8,6 +8,8 @@
 // SPDX-License-Identifier: EPL-2.0
 //
 
+//! Implementation of the 'lint' subcommand
+
 use std::convert::TryFrom;
 use std::path::Path;
 
diff --git a/src/commands/metrics.rs b/src/commands/metrics.rs
index d7f68fb..0efc1e1 100644
--- a/src/commands/metrics.rs
+++ b/src/commands/metrics.rs
@@ -8,6 +8,8 @@
 // SPDX-License-Identifier: EPL-2.0
 //
 
+//! Implementation of the 'metrics' subcommand
+
 use std::path::Path;
 use std::io::Write;
 
diff --git a/src/commands/release.rs b/src/commands/release.rs
index 837ebb8..6f0232b 100644
--- a/src/commands/release.rs
+++ b/src/commands/release.rs
@@ -8,6 +8,8 @@
 // SPDX-License-Identifier: EPL-2.0
 //
 
+//! Implementation of the 'release' subcommand
+
 use std::io::Write;
 use std::path::PathBuf;
 
diff --git a/src/commands/source.rs b/src/commands/source.rs
index 55ca1c3..0fc1eac 100644
--- a/src/commands/source.rs
+++ b/src/commands/source.rs
@@ -8,6 +8,8 @@
 // SPDX-License-Identifier: EPL-2.0
 //
 
+//! Implementation of the 'source' subcommand
+
 use std::io::Write;
 use std::path::PathBuf;
 use std::convert::TryFrom;
diff --git a/src/commands/tree_of.rs b/src/commands/tree_of.rs
index 10e51d3..e632ed5 100644
--- a/src/commands/tree_of.rs
+++ b/src/commands/tree_of.rs
@@ -8,6 +8,8 @@
 // SPDX-License-Identifier: EPL-2.0
 //
 
+//! Implementation of the 'tree-of' subcommand
+
 use std::convert::TryFrom;
 
 use anyhow::Error;
diff --git a/src/commands/util.rs b/src/commands/util.rs
index 5749e66..9ed38d9 100644
--- a/src/commands/util.rs
+++ b/src/commands/util.rs
@@ -8,6 +8,8 @@
 // SPDX-License-Identifier: EPL-2.0
 //
 
+//! Utility module for subcommand implementation helpers
+
 use std::io::Write;
 use std::fmt::Display;
 use std::path::Path;
@@ -109,6 +111,8 @@ where
     }
 }
 
+/// Check whether all phases are available in the package,
+/// generate a nice error message if one is not.
 fn all_phases_available(pkg: &Package, available_phases: &[PhaseName]) -> Result<()> {
     let package_phasenames = pkg.phases().keys().collect::<Vec<_>>();
 
@@ -139,6 +143,7 @@ fn all_phases_available(pkg: &Package, available_phases: &[PhaseName]) -> Result
     Ok(())
 }
 
+/// Helper function to make a package name regex out of a String
 pub fn mk_package_name_regex(regex: &str) -> Result<Regex> {
     let mut builder = regex::RegexBuilder::new(regex);
 
@@ -151,7 +156,7 @@ pub fn mk_package_name_regex(regex: &str) -> Result<Regex> {
         .map_err(Error::from)
 }
 
-
+/// Make a header column for the ascii_table crate
 pub fn mk_header(vec: Vec<&str>) -> Vec<ascii_table::Column> {
     vec.into_iter()
         .map(|name| ascii_table::Column {
@@ -164,6 +169,8 @@ pub fn mk_header(vec: Vec<&str>) -> Vec<ascii_table::Column> {
 
 /// Display the passed data as nice ascii table,
 /// or, if stdout is a pipe, print it nicely parseable
+///
+/// If `csv` is `true`, convert the data to CSV and print that instead.
 pub fn display_data<D: Display>(
     headers: Vec<ascii_table::Column>,
     data: Vec<Vec<D>>,
diff --git a/src/commands/versions_of.rs b/src/commands/versions_of.rs
index 1a709dc..b0aad28 100644
--- a/src/commands/versions_of.rs
+++ b/src/commands/versions_of.rs
@@ -8,6 +8,8 @@
 // SPDX-License-Identifier: EPL-2.0
 //
 
+//! Implementation of the 'versions_of' subcommand
+
 use anyhow::Error;
 use anyhow::Result;
 use clap::ArgMatches;
diff --git a/src/commands/what_depends.rs b/src/commands/what_depends.rs
index 578e067..10c9edc 100644
--- a/src/commands/what_depends.rs
+++ b/src/commands/what_depends.rs
@@ -8,6 +8,8 @@
 // SPDX-License-Identifier: EPL-2.0
 //
 
+//! Implementation of the 'what_depends' subcommand
+
 use anyhow::Result;
 use clap::ArgMatches;
 use log::trace;
diff --git a/src/config/not_validated.rs b/src/config/not_validated.rs
index b005aca..1d041a5 100644
--- a/src/config/not_validated.rs
+++ b/src/config/not_validated.rs
@@ -24,78 +24,108 @@ use crate::package::PhaseName;
 /// The configuration that is loaded from the filesystem
 #[derive(Debug, Getters, Deserialize)]
 pub struct NotValidatedConfiguration {
+
+    /// Compatibility setting
+    ///
+    /// If the version of butido is (semver) incompatible to this setting in the configuration,
+    /// butido won't execute any further because it might fail later due to configuration
+    /// incompatibilities
     #[getset(get = "pub")]
     compatibility: semver::VersionReq,
 
+    /// The directory logs are written to, if logs are requested in plaintext files
     #[getset(get = "pub")]
     log_dir: PathBuf,
 
+    /// Whether the script interpolation feature should be struct, i.e. missing variables result in
+    /// a failing interpolation. This should be `true` for most users.
     #[serde(default = "default_strict_script_interpolation")]
     #[getset(get = "pub")]
     strict_script_interpolation: bool,
 
+    /// The format of the progress bars
     #[serde(default = "default_progress_format")]
     #[getset(get = "pub")]
     progress_format: String,
 
+    /// The format of the spinners in the CLI
     #[serde(default = "default_spinner_format")]
     #[getset(get = "pub")]
     spinner_format: String,
 
+    /// The format used to print a package
+    ///
+    /// This is handlebars syntax
     #[serde(default = "default_package_print_format")]
     #[getset(get = "pub")]
     package_print_format: String,
 
+    /// How many lines should be printed from the log if a build fails
     #[serde(default = "default_build_error_lines")]
     #[getset(get = "pub")]
     build_error_lines: usize,
 
+    /// The theme used to highlight scripts when printing them to the CLI
     #[getset(get = "pub")]
     script_highlight_theme: Option<String>,
 
+    /// The linter executable that is used to lint packaging scripts
     #[getset(get = "pub")]
     script_linter: Option<PathBuf>,
 
+    /// The shebang that is added at the very beginning of the package scripts
     #[serde(default = "default_script_shebang")]
     #[getset(get = "pub")]
     shebang: String,
 
+    /// The directory where releases are stored
     #[serde(rename = "releases_root")]
     #[getset(get = "pub")]
     releases_directory: PathBuf,
 
+    /// The names of the directories inside the `releases_directory` to store different releases in
     #[serde(rename = "release_stores")]
     #[getset(get = "pub")]
     release_stores: Vec<String>,
 
+    /// The directory where intermediate ("staging") artifacts are stored.
+    /// This is used as a root directory, a UUID-named directory will be added below this, using
+    /// the UUID of the submit
     #[serde(rename = "staging")]
     #[getset(get = "pub")]
     staging_directory: PathBuf,
 
+    /// Where the sources are cached
     #[serde(rename = "source_cache")]
     #[getset(get = "pub")]
     source_cache_root: PathBuf,
 
+    /// The hostname used to connect to the database
     #[getset(get = "pub")]
     #[serde(rename = "database_host")]
     database_host: String,
 
+    /// The post used to connect to the database
     #[getset(get = "pub")]
     #[serde(rename = "database_port")]
     database_port: u16,
 
+    /// The user used to connect to the database
     #[getset(get = "pub")]
     #[serde(rename = "database_user")]
     database_user: String,
 
+    /// The password used to connect to the database
     #[getset(get = "pub")]
     #[serde(rename = "database_password")]
     database_password: String,
 
+    /// The name of the database
     #[getset(get = "pub")]
     #[serde(rename = "database_name")]
     database_name: String,
 
+    /// The configuration for the docker endpoints
     #[getset(get = "pub")]
     #[serde(rename = "database_connection_timeout")]
     database_connection_timeout: Option<u16>,
@@ -103,9 +133,11 @@ pub struct NotValidatedConfiguration {
     #[getset(get = "pub")]
     docker: DockerConfig,
 
+    /// The configuration for the containers
     #[getset(get = "pub")]
     containers: ContainerConfig,
 
+    /// The names of the phases which should be compiled into the packaging script
     #[getset(get = "pub")]
     available_phases: Vec<PhaseName>,
 }
diff --git a/src/config/util.rs b/src/config/util.rs
index 4c1deff..132ae0d 100644
--- a/src/config/util.rs
+++ b/src/config/util.rs
@@ -11,14 +11,17 @@
 //! This module contains default functions that are called by serde when deserializing the
 //! configuration and having to use default values.
 
+/// The default progress bar format
 pub fn default_progress_format() -> String {
     String::from("[{elapsed_precise}] ({percent:>3}%): {bar:40.cyan/blue} | {msg}")
 }
 
+/// The default spinner format
 pub fn default_spinner_format() -> String {
     String::from("[{elapsed_precise}] {spinner} | {msg}")
 }
 
+/// The default format that is used to print one package
 pub fn default_package_print_format() -> String {
     String::from(indoc::indoc!(
         r#"
@@ -83,14 +86,17 @@ pub fn default_package_print_format() -> String {
     ))
 }
 
+/// The default value for whether strict script interpolation should be used
 pub fn default_strict_script_interpolation() -> bool {
     true
 }
 
+/// The default value for the shebang
 pub fn default_script_shebang() -> String {
     String::from("#!/bin/bash")
 }
 
+/// The default value for the number of log lines that should be printed if a build fails
 pub fn default_build_error_lines() -> usize {
     10
 }