From 7d63c84468a21a7192dc16d1018c740bf3996d43 Mon Sep 17 00:00:00 2001 From: C L Eckhardt <29362105+CLEckhardt@users.noreply.github.com> Date: Tue, 5 Sep 2023 12:20:06 -0500 Subject: [PATCH] appender: clarify file appender docs (#2689) ## Motivation There are a few errors in the file appender docs - this fixes them. It also wasn't clear/apparent to me that you can create a non-rolling file appender with the `rolling` module - this calls that out more clearly. ## Solution Updates to docs. --- tracing-appender/src/lib.rs | 26 ++++++++++++++++++++------ tracing-appender/src/rolling.rs | 10 +++++----- 2 files changed, 25 insertions(+), 11 deletions(-) diff --git a/tracing-appender/src/lib.rs b/tracing-appender/src/lib.rs index 25279fb0ec..9fe789e50a 100644 --- a/tracing-appender/src/lib.rs +++ b/tracing-appender/src/lib.rs @@ -26,20 +26,34 @@ //! - Using a combination of [`NonBlocking`][non_blocking] and [`RollingFileAppender`][rolling_struct] to allow writes to a log file //! without blocking. //! -//! ## Rolling File Appender +//! ## File Appender +//! +//! The [`rolling` module][rolling] provides functions to create rolling and non-rolling file +//! appenders. +//! +//! Rolling file appender rotation options are [`Rotation::MINUTELY`](rolling::Rotation::MINUTELY), +//! [`Rotation::HOURLY`](rolling::Rotation::HOURLY), and +//! [`Rotation::DAILY`](rolling::Rotation::DAILY). +//! +//! To create a non-rolling file appender, use +//! [`tracing_appender::rolling::never(/*...*/)`](rolling::never) or +//! [`Rotation::NEVER`](rolling::Rotation::NEVER). +//! +//! The following example creates an hourly rotating file appender that writes to +//! `/some/directory/prefix.log.YYYY-MM-DD-HH`: //! //! ```rust //! # fn docs() { //! let file_appender = tracing_appender::rolling::hourly("/some/directory", "prefix.log"); //! # } //! ``` -//! This creates an hourly rotating file appender that writes to `/some/directory/prefix.log.YYYY-MM-DD-HH`. -//! [`Rotation::DAILY`](rolling::Rotation::DAILY) and [`Rotation::NEVER`](rolling::Rotation::NEVER) are the other available options. //! -//! The file appender implements [`std::io::Write`][write]. To be used with [`tracing_subscriber::FmtSubscriber`][fmt_subscriber], -//! it must be combined with a [`MakeWriter`][make_writer] implementation to be able to record tracing spans/event. +//! The file appender implements [`std::io::Write`][write]. To be used with +//! [`tracing_subscriber::FmtSubscriber`][fmt_subscriber], it must be combined with a +//! [`MakeWriter`][make_writer] implementation to be able to record tracing spans/event. //! -//! The [`rolling` module][rolling]'s documentation provides more detail on how to use this file appender. +//! See the [`rolling` module][rolling]'s documentation for more detail on how to use this file +//! appender. //! //! ## Non-Blocking Writer //! diff --git a/tracing-appender/src/rolling.rs b/tracing-appender/src/rolling.rs index 15ae35ba06..cce6139871 100644 --- a/tracing-appender/src/rolling.rs +++ b/tracing-appender/src/rolling.rs @@ -264,7 +264,7 @@ impl fmt::Debug for RollingFileAppender { } } -/// Creates a minutely, rolling file appender. This will rotate the log file once per minute. +/// Creates a minutely-rotating file appender. This will rotate the log file once per minute. /// /// The appender returned by `rolling::minutely` can be used with `non_blocking` to create /// a non-blocking, minutely file appender. @@ -299,7 +299,7 @@ pub fn minutely( RollingFileAppender::new(Rotation::MINUTELY, directory, file_name_prefix) } -/// Creates an hourly, rolling file appender. +/// Creates an hourly-rotating file appender. /// /// The appender returned by `rolling::hourly` can be used with `non_blocking` to create /// a non-blocking, hourly file appender. @@ -334,7 +334,7 @@ pub fn hourly( RollingFileAppender::new(Rotation::HOURLY, directory, file_name_prefix) } -/// Creates a file appender that rotates daily. +/// Creates a daily-rotating file appender. /// /// The appender returned by `rolling::daily` can be used with `non_blocking` to create /// a non-blocking, daily file appender. @@ -370,13 +370,13 @@ pub fn daily( RollingFileAppender::new(Rotation::DAILY, directory, file_name_prefix) } -/// Creates a non-rolling, file appender +/// Creates a non-rolling file appender. /// /// The appender returned by `rolling::never` can be used with `non_blocking` to create /// a non-blocking, non-rotating appender. /// /// The location of the log file will be specified the `directory` passed in. -/// `file_name` specifies the prefix of the log file. No date or time is appended. +/// `file_name` specifies the complete name of the log file (no date or time is appended). /// /// # Examples ///