From d42346dae986ceeda4f6757d48a37c94b6959e59 Mon Sep 17 00:00:00 2001
From: tison <wander4096@gmail.com>
Date: Fri, 2 Aug 2024 21:57:33 +0800
Subject: [PATCH] docs: add keyword, and add docs for rolling file structs

Signed-off-by: tison <wander4096@gmail.com>
---
 Cargo.toml                              |  5 +++++
 src/append/rolling_file/non_blocking.rs | 15 +++++++++++++++
 src/append/rolling_file/rolling.rs      |  8 ++++++++
 3 files changed, 28 insertions(+)

diff --git a/Cargo.toml b/Cargo.toml
index a061004..1414e0f 100644
--- a/Cargo.toml
+++ b/Cargo.toml
@@ -25,6 +25,11 @@ repository = "https://github.com/tisonkun/logforth"
 rust-version = "1.71.0"
 version = "0.7.2"
 
+categories = [
+  "development-tools::debugging",
+]
+keywords = ["logging", "log", "opentelemetry", "fastrace"]
+
 [package.metadata.docs.rs]
 all-features = true
 rustdoc-args = ["--cfg", "docs"]
diff --git a/src/append/rolling_file/non_blocking.rs b/src/append/rolling_file/non_blocking.rs
index b826e9d..0508e39 100644
--- a/src/append/rolling_file/non_blocking.rs
+++ b/src/append/rolling_file/non_blocking.rs
@@ -25,6 +25,19 @@ use crossbeam_channel::Sender;
 use crate::append::rolling_file::worker::Worker;
 use crate::append::rolling_file::Message;
 
+/// A guard that flushes log records associated to a [`NonBlocking`] on a drop.
+///
+/// Writing to a [`NonBlocking`] writer will **not** immediately write the log record to the
+/// underlying output. Instead, the log record will be written by a dedicated logging thread at
+/// some later point. To increase throughput, the non-blocking writer will flush to the underlying
+/// output on a periodic basis rather than every time a log record is written. This means that if
+/// the program terminates abruptly (such as through an uncaught `panic` or a `std::process::exit`),
+/// some log records may not be written.
+///
+/// Since logs near a crash are often necessary for diagnosing the failure, `WorkerGuard` provides a
+/// mechanism to ensure that _all_ buffered logs are flushed to their output. `WorkerGuard` should
+/// be assigned in the `main` function or whatever the entrypoint of the program is. This will
+/// ensure that the guard will be dropped during an unwinding or when `main` exits successfully.
 #[derive(Debug)]
 pub struct WorkerGuard {
     _guard: Option<JoinHandle<()>>,
@@ -72,6 +85,7 @@ impl Drop for WorkerGuard {
     }
 }
 
+/// A non-blocking, off-thread writer.
 #[derive(Clone, Debug)]
 pub struct NonBlocking {
     sender: Sender<Message>,
@@ -110,6 +124,7 @@ impl NonBlocking {
     }
 }
 
+/// A builder for [`NonBlocking`].
 #[derive(Debug)]
 pub struct NonBlockingBuilder {
     thread_name: String,
diff --git a/src/append/rolling_file/rolling.rs b/src/append/rolling_file/rolling.rs
index e26af13..a8c2cd4 100644
--- a/src/append/rolling_file/rolling.rs
+++ b/src/append/rolling_file/rolling.rs
@@ -30,6 +30,7 @@ use time::Duration;
 use time::OffsetDateTime;
 use time::Time;
 
+/// A file writer with the ability to rotate log files at a fixed schedule.
 #[derive(Debug)]
 pub struct RollingFileWriter {
     state: State,
@@ -63,6 +64,7 @@ impl Write for RollingFileWriter {
     }
 }
 
+/// A builder for [`RollingFileWriter`].
 #[derive(Debug)]
 pub struct RollingFileWriterBuilder {
     rotation: Rotation,
@@ -313,12 +315,18 @@ fn open_file(dir: &Path, filename: &str) -> anyhow::Result<File> {
         .context("failed to create log file")
 }
 
+/// Defines a fixed period for rolling of a log file.
 #[derive(Clone, Eq, PartialEq, Debug)]
 pub enum Rotation {
+    /// Minutely Rotation
     Minutely,
+    /// Hourly Rotation
     Hourly,
+    /// Daily Rotation
     Daily,
+    /// No Rotation
     Never,
+    // TODO(tisonkun): consider support rotating on file size exceeding a threshold.
 }
 
 impl Rotation {