WIP

spdlog/src/error.rs

@@ -1,4 +1,9 @@
 //! Provides error types.
+//!
+//! # Default error handler
+//!
+//! If a logger or sink does not have an error handler set up, a default error
+//! handler will be used, which will print the error to `stderr`.
 
 use std::{
     fmt::{self, Display},

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
 ///
@@ -55,7 +99,7 @@ impl FmtExtraInfo {
         FmtExtraInfo::default()
     }
 
-    /// Constructs a [`FmtExtraInfoBuilder`].
+    /// Gets a [`FmtExtraInfoBuilder`].
     #[must_use]
     pub fn builder() -> FmtExtraInfoBuilder {
         FmtExtraInfoBuilder::new()
@@ -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
 /// 

spdlog/src/level.rs

@@ -11,10 +11,11 @@ pub(crate) const LOG_LEVEL_NAMES: [&str; Level::count()] =
 
 const LOG_LEVEL_SHORT_NAMES: [&str; Level::count()] = ["C", "E", "W", "I", "D", "T"];
 
-/// An enum representing log levels.
+/// Represents log levels.
 ///
-/// Typical usage includes: specifying the `Level` of [`log!`], and comparing a
-/// `Level` to a [`LevelFilter`] through [`LevelFilter::compare`].
+/// Typical usage:
+/// - specifying the `level` parameter of macro [`log!`],
+/// - comparing a `Level` to a [`LevelFilter`] through [`LevelFilter::compare`].
 ///
 /// # Note
 ///
@@ -117,7 +118,7 @@ impl Level {
         Level::Trace
     }
 
-    /// Returns the string representation of the `Level`.
+    /// Returns the string representation.
     ///
     /// This returns the same string as the `fmt::Display` implementation.
     #[must_use]
@@ -130,7 +131,7 @@ impl Level {
         LOG_LEVEL_SHORT_NAMES[*self as usize]
     }
 
-    /// Iterate through all supported logging levels.
+    /// Iterates through all logging levels.
     ///
     /// The order of iteration is from more severe to more verbose.
     ///
@@ -182,23 +183,10 @@ impl FromStr for Level {
     }
 }
 
-/// An enum representing log level logical filter conditions.
+/// Represents log level logical filter conditions.
 ///
-/// A `LevelFilter` may be compared to a [`Level`] through
-/// [`LevelFilter::compare`].
-///
-/// # Examples
-///
-/// ```
-/// use spdlog::prelude::*;
-///
-/// let level_filter: LevelFilter = LevelFilter::MoreSevere(Level::Info);
-///
-/// assert_eq!(level_filter.compare(Level::Trace), false);
-/// assert_eq!(level_filter.compare(Level::Info), false);
-/// assert_eq!(level_filter.compare(Level::Warn), true);
-/// assert_eq!(level_filter.compare(Level::Error), true);
-/// ```
+/// Use [`LevelFilter::compare`] method to check if a [`Level`] satisfies the
+/// filter condition.
 #[repr(align(4))]
 #[derive(Copy, Clone, Eq, PartialEq, Hash, Debug)]
 pub enum LevelFilter {
@@ -234,11 +222,20 @@ cfg_if! {
 }
 
 impl LevelFilter {
-    /// Compares the given level with the logical filter condition
+    /// Checks the given level if satisfies the filter condition.
     ///
     /// # Examples
     ///
-    /// See the documentation of [`LevelFilter`].
+    /// ```
+    /// use spdlog::prelude::*;
+    ///
+    /// let level_filter: LevelFilter = LevelFilter::MoreSevere(Level::Info);
+    ///
+    /// assert_eq!(level_filter.compare(Level::Trace), false);
+    /// assert_eq!(level_filter.compare(Level::Info), false);
+    /// assert_eq!(level_filter.compare(Level::Warn), true);
+    /// assert_eq!(level_filter.compare(Level::Error), true);
+    /// ```
     #[must_use]
     pub fn compare(&self, level: Level) -> bool {
         self.__compare_const(level)