From 946895a1e1086d9c692d9a504ce4ecbe2d8da5e4 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
 ///