Cargo fmt error fix module docs

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 <path/to/agentmon/binary>
+//! ```
+
 // 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 <path/to/agentmon/binary>
-/// ```
-
 /// Turn CLI arguments into a Rust struct
 #[derive(Parser, Debug)]
 struct Args {

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

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

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}");

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<dyn StartedLogger>;
     fn without_buildpack_name(self) -> Box<dyn StartedLogger>;

commons/src/output/section_log.rs

@@ -1,44 +1,43 @@
+//! Write to the build output in a `Box<dyn SectionLogger>` 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<dyn StartedLogger>::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<Self::Buildpack>,
+//! //     layer_path: &std::path::Path,
+//! // ) -> Result<
+//! //     libcnb::layer::LayerResult<Self::Metadata>,
+//! //     <Self::Buildpack as libcnb::Buildpack>::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<dyn SectionLogger>` 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<dyn StartedLogger>::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<Self::Buildpack>,
-/// //     layer_path: &std::path::Path,
-/// // ) -> Result<
-/// //     libcnb::layer::LayerResult<Self::Metadata>,
-/// //     <Self::Buildpack as libcnb::Buildpack>::Error,
-/// // > {
-/// log_step_timed("Installing", || {
-///         // Install logic here
-///         todo!()
-///     })
-/// // }
-/// ```
-
 /// Output a message as a single step, ideally a short message
 ///
 /// ```

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<Self>) -> libcnb::Result<BuildResult, Self::Error> {
+//!     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<Self>) -> libcnb::Result<BuildResult, Self::Error> {
+//!     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<Rc<()>>;
 
 thread_local!(static WARN_LATER: RefCell<Option<Vec<String>>> = 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<Self>) -> libcnb::Result<BuildResult, Self::Error> {
-///     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<Self>) -> libcnb::Result<BuildResult, Self::Error> {
-///     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