From 5b0f1e53e163288b03ed7553c140e33337197c5b Mon Sep 17 00:00:00 2001 From: Schneems Date: Wed, 11 Dec 2024 12:55:41 -0600 Subject: [PATCH] Cargo fmt error fix module docs --- buildpacks/ruby/src/bin/agentmon_loop.rs | 20 ++-- buildpacks/ruby/src/bin/launch_daemon.rs | 4 +- commons/src/output/background_timer.rs | 6 +- commons/src/output/fmt.rs | 3 +- commons/src/output/interface.rs | 14 +-- commons/src/output/section_log.rs | 69 ++++++------ commons/src/output/warn_later.rs | 132 +++++++++++------------ 7 files changed, 123 insertions(+), 125 deletions(-) diff --git a/buildpacks/ruby/src/bin/agentmon_loop.rs b/buildpacks/ruby/src/bin/agentmon_loop.rs index f26c8363..7ac2347d 100644 --- a/buildpacks/ruby/src/bin/agentmon_loop.rs +++ b/buildpacks/ruby/src/bin/agentmon_loop.rs @@ -1,3 +1,13 @@ +//! Agentmon Loop +//! +//! Boots agentmon (a statsd server) in a loop +//! +//! Example: +//! +//! ```shell +//! $ cargo run --bin agentmon_loop -- --path +//! ``` + // Required due to: https://github.com/rust-lang/rust/issues/95513 #![allow(unused_crate_dependencies)] @@ -19,16 +29,6 @@ static HEROKU_METRICS_URL: &str = "HEROKU_METRICS_URL"; const SLEEP_FOR: Duration = Duration::from_secs(1); -/// Agentmon Loop -/// -/// Boots agentmon (a statsd server) in a loop -/// -/// Example: -/// -/// ```shell -/// $ cargo run --bin agentmon_loop -- --path -/// ``` - /// Turn CLI arguments into a Rust struct #[derive(Parser, Debug)] struct Args { diff --git a/buildpacks/ruby/src/bin/launch_daemon.rs b/buildpacks/ruby/src/bin/launch_daemon.rs index 19cf5f38..6992248e 100644 --- a/buildpacks/ruby/src/bin/launch_daemon.rs +++ b/buildpacks/ruby/src/bin/launch_daemon.rs @@ -1,3 +1,5 @@ +//! Schedules agentmon to run as a background daemon + // Required due to: https://github.com/rust-lang/rust/issues/95513 #![allow(unused_crate_dependencies)] @@ -8,8 +10,6 @@ use std::process::Command; static AGENTMON_DEBUG: &str = "AGENTMON_DEBUG"; -/// Schedules agentmon to run as a background daemon - /// CLI argument parser /// /// ```shell diff --git a/commons/src/output/background_timer.rs b/commons/src/output/background_timer.rs index 05a02c10..f768644d 100644 --- a/commons/src/output/background_timer.rs +++ b/commons/src/output/background_timer.rs @@ -1,12 +1,12 @@ +//! This module is responsible for the logic involved in the printing to output while +//! other work is being performed. +//! use std::io::Write; use std::sync::mpsc::Sender; use std::sync::{mpsc, Arc, Mutex}; use std::thread::JoinHandle; use std::time::{Duration, Instant}; -/// This module is responsible for the logic involved in the printing to output while -/// other work is being performed. - /// Prints a start, then a tick every second, and an end to the given `Write` value. /// /// Returns a struct that allows for manually stopping the timer or will automatically stop diff --git a/commons/src/output/fmt.rs b/commons/src/output/fmt.rs index 693c4f2b..f5f27037 100644 --- a/commons/src/output/fmt.rs +++ b/commons/src/output/fmt.rs @@ -1,9 +1,8 @@ +//! Helpers for formatting and colorizing your output use crate::output::util::LinesWithEndings; use const_format::formatcp; use std::fmt::Write; -/// Helpers for formatting and colorizing your output - /// Decorated str for prefixing "Help:" #[deprecated(since = "0.0.0", note = "Use `bullet_stream` instead")] pub const HELP: &str = formatcp!("{IMPORTANT_COLOR}! HELP{RESET}"); diff --git a/commons/src/output/interface.rs b/commons/src/output/interface.rs index 46dc615b..c4da4ec6 100644 --- a/commons/src/output/interface.rs +++ b/commons/src/output/interface.rs @@ -1,13 +1,13 @@ +//! Consuming stateful logger interface +//! +//! The log pattern used by `BuildLog` is a consuming state machine that is designed to minimize +//! the amount of mistakes that can result in malformed build output. +//! +//! The interface isn't stable and may need to change. +//! use std::fmt::Debug; use std::io::Write; -/// Consuming stateful logger interface -/// -/// The log pattern used by `BuildLog` is a consuming state machine that is designed to minimize -/// the amount of mistakes that can result in malformed build output. -/// -/// The interface isn't stable and may need to change. - pub trait Logger: Debug { fn buildpack_name(self, s: &str) -> Box; fn without_buildpack_name(self) -> Box; diff --git a/commons/src/output/section_log.rs b/commons/src/output/section_log.rs index a4ffbb71..44883426 100644 --- a/commons/src/output/section_log.rs +++ b/commons/src/output/section_log.rs @@ -1,44 +1,43 @@ +//! Write to the build output in a `Box` format with functions +//! +//! ## What +//! +//! Logging from within a layer can be difficult because calls to the layer interface are not +//! mutable nor consumable. Functions can be used at any time with no restrictions. The +//! only downside is that the buildpack author (you) is now responsible for: +//! +//! - Ensuring that `Box::section()` was called right before any of these +//! functions are called. +//! - Ensuring that you are not attempting to log while already logging i.e. calling `step()` within a +//! `step_timed()` call. +//! +//! ## Use +//! +//! The main use case is logging inside of a layer: +//! +//! ```no_run +//! use commons::output::section_log::log_step_timed; +//! +//! // fn create( +//! // &self, +//! // context: &libcnb::build::BuildContext, +//! // layer_path: &std::path::Path, +//! // ) -> Result< +//! // libcnb::layer::LayerResult, +//! // ::Error, +//! // > { +//! log_step_timed("Installing", || { +//! // Install logic here +//! todo!() +//! }) +//! // } +//! ``` use crate::output::build_log::{state, BuildData, BuildLog}; #[allow(clippy::wildcard_imports)] pub use crate::output::interface::*; use std::io::Stdout; use std::marker::PhantomData; -/// Write to the build output in a `Box` format with functions -/// -/// ## What -/// -/// Logging from within a layer can be difficult because calls to the layer interface are not -/// mutable nor consumable. Functions can be used at any time with no restrictions. The -/// only downside is that the buildpack author (you) is now responsible for: -/// -/// - Ensuring that `Box::section()` was called right before any of these -/// functions are called. -/// - Ensuring that you are not attempting to log while already logging i.e. calling `step()` within a -/// `step_timed()` call. -/// -/// ## Use -/// -/// The main use case is logging inside of a layer: -/// -/// ```no_run -/// use commons::output::section_log::log_step_timed; -/// -/// // fn create( -/// // &self, -/// // context: &libcnb::build::BuildContext, -/// // layer_path: &std::path::Path, -/// // ) -> Result< -/// // libcnb::layer::LayerResult, -/// // ::Error, -/// // > { -/// log_step_timed("Installing", || { -/// // Install logic here -/// todo!() -/// }) -/// // } -/// ``` - /// Output a message as a single step, ideally a short message /// /// ``` diff --git a/commons/src/output/warn_later.rs b/commons/src/output/warn_later.rs index 1de8c83b..ae361a97 100644 --- a/commons/src/output/warn_later.rs +++ b/commons/src/output/warn_later.rs @@ -1,3 +1,69 @@ +//! Queue a warning for later +//! +//! Build logs can be quite large and people don't always scroll back up to read every line. Delaying +//! a warning and emitting it right before the end of the build can increase the chances the app +//! developer will read it. +//! +//! ## Use - Setup a `WarnGuard` in your buildpack +//! +//! To ensure warnings are printed, even in the event of errors, you must create a `WarnGuard` +//! in your buildpack that will print any delayed warnings when dropped: +//! +//! ```no_run +//! // src/main.rs +//! use commons::output::warn_later::WarnGuard; +//! +//! // fn build(&self, context: BuildContext) -> libcnb::Result { +//! let warn_later = WarnGuard::new(std::io::stdout()); +//! // ... +//! +//! // Warnings will be emitted when the warn guard is dropped +//! drop(warn_later); +//! // } +//! ``` +//! +//! Alternatively you can manually print delayed warnings: +//! +//! ```no_run +//! use commons::output::warn_later::WarnGuard; +//! +//! // fn build(&self, context: BuildContext) -> libcnb::Result { +//! let warn_later = WarnGuard::new(std::io::stdout()); +//! // ... +//! +//! // Consumes the guard, prints and clears any delayed warnings. +//! warn_later.warn_now(); +//! // } +//! ``` +//! +//! ## Use - Issue a delayed warning +//! +//! Once a warn guard is in place you can queue a warning using `section_log::log_warning_later` or `build_log::*`: +//! +//! ``` +//! use commons::output::warn_later::WarnGuard; +//! use commons::output::build_log::*; +//! +//! // src/main.rs +//! let warn_later = WarnGuard::new(std::io::stdout()); +//! +//! BuildLog::new(std::io::stdout()) +//! .buildpack_name("Julius Caesar") +//! .announce() +//! .warn_later("Beware the ides of march"); +//! ``` +//! +//! ``` +//! use commons::output::warn_later::WarnGuard; +//! use commons::output::section_log::log_warning_later; +//! +//! // src/main.rs +//! let warn_later = WarnGuard::new(std::io::stdout()); +//! +//! // src/layers/greenday.rs +//! log_warning_later("WARNING: Live without warning"); +//! ``` + use indoc::formatdoc; use std::cell::RefCell; use std::fmt::{Debug, Display}; @@ -10,72 +76,6 @@ pub type PhantomUnsync = PhantomData>; thread_local!(static WARN_LATER: RefCell>> = const { RefCell::new(None) }); -/// Queue a warning for later -/// -/// Build logs can be quite large and people don't always scroll back up to read every line. Delaying -/// a warning and emitting it right before the end of the build can increase the chances the app -/// developer will read it. -/// -/// ## Use - Setup a `WarnGuard` in your buildpack -/// -/// To ensure warnings are printed, even in the event of errors, you must create a `WarnGuard` -/// in your buildpack that will print any delayed warnings when dropped: -/// -/// ```no_run -/// // src/main.rs -/// use commons::output::warn_later::WarnGuard; -/// -/// // fn build(&self, context: BuildContext) -> libcnb::Result { -/// let warn_later = WarnGuard::new(std::io::stdout()); -/// // ... -/// -/// // Warnings will be emitted when the warn guard is dropped -/// drop(warn_later); -/// // } -/// ``` -/// -/// Alternatively you can manually print delayed warnings: -/// -/// ```no_run -/// use commons::output::warn_later::WarnGuard; -/// -/// // fn build(&self, context: BuildContext) -> libcnb::Result { -/// let warn_later = WarnGuard::new(std::io::stdout()); -/// // ... -/// -/// // Consumes the guard, prints and clears any delayed warnings. -/// warn_later.warn_now(); -/// // } -/// ``` -/// -/// ## Use - Issue a delayed warning -/// -/// Once a warn guard is in place you can queue a warning using `section_log::log_warning_later` or `build_log::*`: -/// -/// ``` -/// use commons::output::warn_later::WarnGuard; -/// use commons::output::build_log::*; -/// -/// // src/main.rs -/// let warn_later = WarnGuard::new(std::io::stdout()); -/// -/// BuildLog::new(std::io::stdout()) -/// .buildpack_name("Julius Caesar") -/// .announce() -/// .warn_later("Beware the ides of march"); -/// ``` -/// -/// ``` -/// use commons::output::warn_later::WarnGuard; -/// use commons::output::section_log::log_warning_later; -/// -/// // src/main.rs -/// let warn_later = WarnGuard::new(std::io::stdout()); -/// -/// // src/layers/greenday.rs -/// log_warning_later("WARNING: Live without warning"); -/// ``` - /// Pushes a string to a thread local warning vec for to be emitted later /// /// # Errors