WIP

spdlog/src/formatter/full_formatter.rs

@@ -10,28 +10,28 @@ use crate::{
 };
 
 #[rustfmt::skip]
-/// A full info log records formatter.
+/// Full information logs formatter.
 ///
-/// It is the default formatter for sinks.
+/// It is the default formatter for most sinks.
 ///
 /// Log messages formatted by it look like:
 ///
 ///  - Default:
 ///
 ///    <pre>
-///    [2022-11-02 09:23:12.263] [<font color="#11D116">info</font>] hello, world!
+///    [2022-11-02 09:23:12.263] [<font color="#0DBC79">info</font>] hello, world!
 ///    </pre>
 ///
 ///  - If the logger has a name:
 ///
 ///    <pre>
-///    [2022-11-02 09:23:12.263] [logger-name] [<font color="#11D116">info</font>] hello, world!
+///    [2022-11-02 09:23:12.263] [logger-name] [<font color="#0DBC79">info</font>] hello, world!
 ///    </pre>
 /// 
 ///  - If crate feature `source-location` is enabled:
 ///
 ///    <pre>
-///    [2022-11-02 09:23:12.263] [<font color="#11D116">info</font>] [mod::path, src/main.rs:4] hello, world!
+///    [2022-11-02 09:23:12.263] [logger-name] [<font color="#0DBC79">info</font>] [mod::path, src/main.rs:4] hello, world!
 ///    </pre>
 #[derive(Clone)]
 pub struct FullFormatter {

spdlog/src/formatter/mod.rs

@@ -1,8 +1,52 @@
 //! Provides formatters for sink formatting log records.
 //!
-//! Usually use [`Sink::set_formatter`] to set the formatter of a sink.
+//! # Formatter
+//!
+//! Each normal Sink owns a Formatter, which is used to format each log.
+//!
+//! The default formatter for most sinks is [`FullFormatter`], you can call
+//! [`Sink::set_formatter`] to replace it with another formatter.
+//!
+//! The easiest way to make a custom formatter is to build a pattern, see
+//! [Compile-time and runtime pattern
+//! formatter](#compile-time-and-runtime-pattern-formatter) below. If pattern
+//! isn't flexible enough for you, you need to implement [`Formatter`] trait for
+//! your own formatter struct. See the implementation of [`FullFormatter`] and
+//! [./examples] directory for examples.
+//!
+//! # Compile-time and runtime pattern formatter
+//!
+//! spdlog-rs supports formatting your log records according to a pattern
+//! string. There are 2 ways to construct a pattern:
+//!
+//! - Macro [`pattern!`]: Builds a pattern at compile-time.
+//! - Macro [`runtime_pattern!`]: Builds a pattern at runtime.
+//!
+//! ```
+//! use spdlog::formatter::{pattern, PatternFormatter};
+//! # use spdlog::sink::{Sink, WriteSink};
+//!
+//! # fn main() -> Result<(), Box<dyn std::error::Error>> {
+//! // This pattern is built at compile-time, the template accepts only a literal string.
+//! let pattern = pattern!("[{date} {time}.{millisecond}] [{level}] {payload}{eol}");
+//!
+//! #[cfg(feature = "runtime-pattern")]
+//! {
+//!     use spdlog::formatter::runtime_pattern;
+//!
+//!     // This pattern is built at runtime, the template accepts a runtime string.
+//!     let input = "[{date} {time}.{millisecond}] [{level}] {payload}{eol}";
+//!     let pattern = runtime_pattern!(input)?;
+//! }
+//!
+//! // Use the compile-time or runtime pattern.
+//! # let your_sink = WriteSink::builder().target(vec![]).build()?;
+//! your_sink.set_formatter(Box::new(PatternFormatter::new(pattern)));
+//! # Ok(()) }
+//! ```
 //!
 //! [`Sink::set_formatter`]: crate::sink::Sink::set_formatter
+//! [./examples]: https://github.com/SpriteOvO/spdlog-rs/tree/main/spdlog/examples
 
 mod full_formatter;
 #[cfg(any(
@@ -26,7 +70,7 @@ pub use pattern_formatter::*;
 
 use crate::{Record, Result, StringBuf};
 
-/// A trait for log records formatters.
+/// Represents a formatter that can be used for formatting logs.
 ///
 /// # Examples
 ///
@@ -75,13 +119,7 @@ impl FmtExtraInfo {
     }
 }
 
-/// The builder of [`FmtExtraInfo`].
-///
-/// # Examples
-///
-/// See the implementation of [`FullFormatter`] and [./examples] directory.
-///
-/// [./examples]: https://github.com/SpriteOvO/spdlog-rs/tree/main/spdlog/examples
+#[allow(missing_docs)]
 #[derive(Clone, Eq, PartialEq, Hash, Debug, Default)]
 pub struct FmtExtraInfoBuilder {
     info: FmtExtraInfo,

spdlog/src/formatter/pattern_formatter/mod.rs

@@ -29,7 +29,7 @@ use crate::{
 };
 
 #[rustfmt::skip] // rustfmt currently breaks some empty lines if `#[doc = include_str!("xxx")]` exists
-/// Build a pattern from a template literal string at compile-time.
+/// Builds a pattern from a template literal string at compile-time.
 ///
 /// It accepts inputs in the form:
 ///
@@ -304,7 +304,7 @@ use crate::{
 /// );
 /// ```
 ///
-/// # Appendix: A Full List of Built-in Patterns
+/// # Appendix: Full List of Built-in Patterns
 ///
 /// | Placeholders          | Description                  | Example                                      |
 /// | --------------------- | ---------------------------- | -------------------------------------------- |
@@ -354,7 +354,7 @@ use crate::{
 /// [`FullFormatter`]: crate::formatter::FullFormatter
 pub use ::spdlog_macros::pattern;
 
-/// A formatter that formats log records according to a specified pattern.
+/// Formats logs according to a specified pattern.
 #[derive(Clone)]
 pub struct PatternFormatter<P> {
     pattern: P,
@@ -392,20 +392,22 @@ where
     }
 }
 
-/// Provide context for patterns.
+/// Provides context for patterns.
+///
+/// There is nothing to set up here at the moment, reserved for future use.
 #[derive(Clone, Debug)]
 pub struct PatternContext {
     fmt_info_builder: FmtExtraInfoBuilder,
 }
 
 impl PatternContext {
-    /// Create a new `PatternContext` object.
+    /// Creates a new `PatternContext` object.
     #[must_use]
     fn new(fmt_info_builder: FmtExtraInfoBuilder) -> Self {
         Self { fmt_info_builder }
     }
 
-    /// Set the style range of the log message written by the patterns.
+    /// Sets the style range of the log message written by the patterns.
     ///
     /// This function is reserved for use by the style range pattern. Other
     /// built-in patterns should not use this function. User-defined
@@ -416,26 +418,24 @@ impl PatternContext {
     }
 }
 
-/// A pattern.
+/// Represents a pattern for replacing a placeholder in templates.
 ///
-/// A pattern is like a formatter, except that multiple patterns can be combined
-/// in various ways to create a new pattern. The [`PatternFormatter`] struct
-/// provides a [`Formatter`] that formats log records according to a given
-/// pattern.
+/// A pattern will be used to replace placeholders that appear in a template
+/// string. Multiple patterns can form a new pattern. The [`PatternFormatter`]
+/// formats logs according to a given pattern.
 ///
 /// # Built-in Patterns
 ///
-/// `spdlog` provides a rich set of built-in patterns. See the [`pattern`]
+/// `spdlog-rs` provides a rich set of built-in patterns. See the [`pattern`]
 /// macro.
 ///
 /// # Custom Patterns
 ///
 /// There are 3 approaches to create your own pattern:
-/// - Define a new type and implements this trait;
-/// - Use the [`pattern`] macro to create a pattern from a literal template
+/// - Define a new type and implement this trait;
+/// - Use [`pattern`] macro to create a pattern from a literal template string.
+/// - Use [`runtime_pattern`] macro to create a pattern from a runtime template
 ///   string.
-/// - Use the [`runtime_pattern`] macro to create a pattern from a runtime
-///   template string.
 pub trait Pattern: Send + Sync + DynClone {
     /// Format this pattern against the given log record and write the formatted
     /// message into the output buffer.

spdlog/src/formatter/pattern_formatter/runtime.rs

@@ -17,7 +17,7 @@ type PatternCreator = Box<dyn Fn() -> Box<dyn Pattern>>;
 type PatternRegistry = GenericPatternRegistry<PatternCreator>;
 type PatternKind = GenericPatternKind<PatternCreator>;
 
-/// Build a pattern from a template string at runtime.
+/// Builds a pattern from a template string at runtime.
 ///
 /// It accepts inputs in the form:
 ///
@@ -58,7 +58,7 @@ type PatternKind = GenericPatternKind<PatternCreator>;
 pub use spdlog_macros::runtime_pattern;
 
 #[rustfmt::skip] // rustfmt currently breaks some empty lines if `#[doc = include_str!("xxx")]` exists
-/// A runtime pattern built via [`runtime_pattern!`] macro.
+/// Runtime pattern built via [`runtime_pattern!`] macro.
 ///
 /// ## Basic Usage
 ///