Improve and fill gaps in code docs

src/deploy/mod.rs

@@ -19,6 +19,11 @@ use crate::configparser::{get_profile_config, ChallengeConfig};
 use crate::utils::TryJoinAll;
 
 /// check to make sure that the needed ingress charts are deployed and running
+///
+/// # Errors
+/// If the kubernetes client encounters an error, that error is returned.
+/// Otherwise, an error is returned if a chart is either not deployed or
+/// in a failed state.
 pub async fn check_setup(profile: &ProfileConfig) -> Result<()> {
     let kube = kube_client(profile).await?;
     let secrets: kube::Api<Secret> = kube::Api::namespaced(kube, cluster_setup::INGRESS_NAMESPACE);
@@ -112,7 +117,15 @@ pub async fn check_setup(profile: &ProfileConfig) -> Result<()> {
     }
 }
 
-/// For each challenge, deploy/upload all components of the challenge
+/// Deploy and upload all components of all challenges in `build_results`.
+///
+/// # Errors
+/// If any challenge deployment(s) error, the first error will be
+/// returned.
+///
+/// # Panics
+/// Acquiring the mutex lock should never actually happen because the lock
+/// isn't held across an await point.
 pub async fn deploy_challenges(
     profile_name: &str,
     build_results: &[(&ChallengeConfig, BuildResult)],
@@ -140,6 +153,12 @@ pub async fn deploy_challenges(
 }
 
 /// Deploy / upload all components of a single challenge.
+///
+/// # Errors
+/// The first error is returned from (in order):
+/// 1. kubernetes manifest application
+/// 2. asset uploads
+/// 3. updating challenge info in the frontend application
 async fn deploy_single_challenge(
     profile_name: &str,
     chal: &ChallengeConfig,

src/utils/mod.rs

@@ -32,7 +32,12 @@ where
 // Minijinja strict rendering with error
 //
 
-/// Similar to minijinja.render!(), but return Error if any undefined values.
+/// Similar to minijinja.render!(), but strictly disallows undefined
+/// template variables.
+///
+/// # Errors
+/// If any template variables are undefined, an error will be returned.
+/// See docs for `minijinja.render!` for additional error conditions.
 pub fn render_strict(template: &str, context: minijinja::Value) -> Result<String> {
     let mut strict_env = minijinja::Environment::new();
     // error on any undefined template variables