WIP

spdlog/src/lib.rs

@@ -1,9 +1,10 @@
-//! A fast and combinable Rust logging crate.
+//! Fast, highly configurable Rust logging crate.
 //!
-//! It is inspired by the C++ logging library [spdlog], so if you are familiar
-//! with C++ `spdlog`, you should be able to get started with this crate quite
-//! easily. Of course, there are some differences, you can see [Significant
-//! differences from C++ spdlog](#significant-differences-from-c-spdlog) below.
+//! It is inspired by the C++ logging library [spdlog], and we share most of the
+//! same concepts. So if you are already familiar with C++ `spdlog`, you should
+//! be able to get started with this crate quite easily. Of course, there are
+//! some differences, you can see [Significant differences from C++
+//! spdlog](#significant-differences-from-c-spdlog) below.
 //!
 //! # Getting started
 //!
@@ -13,50 +14,126 @@
 //! spdlog-rs = "0.3"
 //! ```
 //!
-//! `spdlog-rs` is out-of-the-box, it has a default logger, so users can output
-//! logs to terminal by default without any configuration. For more details
-//! about the default logger, please read the documentation of
-//! [`default_logger`].
-//!
-//! The basic use of this crate is through these logging macros: [`trace!`],
-//! [`debug!`], [`info!`], [`warn!`], [`error!`], [`critical!`] and [`log!`],
-//! where [`critical!`] represents the most severe log messages and [`trace!`]
-//! the most verbose. Each of these macros accept format strings similarly to
-//! [`println!`]. All log macros and common types are already under [`prelude`]
-//! module.
-//!
-//! [`Logger`] and [`sink`] are the most important components of `spdlog-rs`.
-//! Make sure to read their documentation. In short, a logger contains a
-//! combination of sinks, and sinks implement writing log messages to actual
-//! targets.
-//!
-//! ## Examples
+//! `spdlog-rs` is highly configurable, but also works out-of-the-box for
+//! lightweight projects. By default, logs will be output to `stdout` and
+//! `stderr`.
 //!
 //! ```
 //! use spdlog::prelude::*;
 //!
-//! info!("hello world!");
-//! warn!("3 + 2 = {}", 5);
+//! // Non-severe logs (trace, debug) are ignored by default.
+//! // If you wish to enable all logs, call
+//! spdlog::default_logger().set_level_filter(spdlog::LevelFilter::All);
+//!
+//! info!("hello, world!");
 //! error!("oops!");
+//! debug!("3 + 2 = {}", 5);
 //! ```
 //!
 //! Output:
 //!
 //! <pre>
-//! [2022-11-02 09:23:12.263] [<font color="#11D116">info</font>] hello, world!
-//! [2022-11-02 09:23:12.263] [<font color="#FDBC4B">warn</font>] 3 + 2 = 5
-//! [2022-11-02 09:23:12.263] [<font color="#C0392B">error</font>] oops!
+//! [2022-11-02 09:23:12.263] [<font color="#0DBC79">info</font>] hello, world!
+//! [2022-11-02 09:23:12.263] [<font color="#F35E5E">error</font>] oops!
+//! [2022-11-02 09:23:12.263] [<font color="#11A8CD">warn</font>] 3 + 2 = 5
 //! </pre>
 //!
-//! If you want to learn more advanced features such as *asynchronous sink*,
-//! *compile-time pattern formatter*, etc., please see [./examples]
-//! directory.
+//! The basic use is through these logging macros: [`trace!`], [`debug!`],
+//! [`info!`], [`warn!`], [`error!`], [`critical!`], where `critical!`
+//! represents the most severe logs and `trace!` the most verbose. Each of these
+//! macros accept format strings similarly to [`println!`]. All log macros
+//! and common types are already under [`prelude`] module.
+//!
+//! # Sink
+//!
+//! Many real programs want more than just displaying logs to the terminal.
+//!
+//! [`Sink`]s are the objects that actually write logs to their targets. If you
+//! want logs to be written to files as well, [`FileSink`] is what you need.
+//!
+//! ```
+//! use spdlog::{prelude::*, sink::FileSink};
+//!
+//! let path = "path/to/somewhere.log";
+//!
+//! # let path = concat!(env!("OUT_DIR"), "/doctest-out/crate-1.txt");
+//! let new_logger = spdlog::default_logger().fork_with(|new| {
+//!     let file_sink = FileSink::builder().path(path).build()?;
+//!     new.sinks_mut().push(new_sink);
+//!     Ok(())
+//! });
+//! # let backup = spdlog::default_logger();
+//! spdlog::set_default_logger(new_logger);
+//!
+//! info!("from now on, logs will be written to both stdout/stderr and the file");
+//!
+//! # assert_eq!(std::fs::read_to_string(path), "this log will be written to a file");
+//! # spdlog::set_default_logger(backup);
+//! ```
+//!
+//! Take a look at [`sink`] module for more interesting sinks, such as
+//! [`RotatingFileSink`] that automatically rotates files by time point or file
+//! size, and [`AsyncPoolSink`] that outputs logs asynchronously.
+//!
+//! # Logger
+//!
+//! A complex program may consist of many separated components.
+//!
+//! [`Logger`] manages, controls and invokes multiple sinks within it. In
+//! addition to having the global [`default_logger`], more loggers are allowed
+//! to be configured, stored and used independently.
 //!
-//! ## Help
+//! Logging macros provide an optional parameter `logger`. If it is specified,
+//! logs will be processed by the specified logger instead of the global default
+//! logger.
 //!
-//! If you have any questions or need help while using this crate, feel free to
-//! [open a discussion]. For feature requests or bug reports, please [open an
-//! issue].
+//! And benefiting from the fact that a logger uses `Arc` to store sinks, a sink
+//! can be set and used by more than one logger, and you can combine them as you
+//! like.
+//!
+//! ```
+//! use spdlog::prelude::*;
+//! # use spdlog::Result;
+//!
+//! struct AppDatabase {
+//!     logger: Logger,
+//!     // ...
+//! }
+//!
+//! impl AppDatabase {
+//!     fn new() -> Result<Self> {
+//!         let logger = Logger::builder()
+//!             .name("database")
+//!             // .sink( ... )
+//!             // .sink( ... )
+//!             // .level_filter( ... )
+//!             .build()?;
+//!         Ok(Self { logger, /* ... */ })
+//!     }
+//!
+//!     fn query<T>(&self, /* ... */) -> T {
+//!         let data = /* Query from the database */
+//!         # 114514;
+//!         trace!(logger: self.logger, "queried data {}", data);
+//!         data
+//!     }
+//! }
+//!
+//! struct AppNetwork { /* ... */ }
+//! struct AppAuth { /* ... */ }
+//! struct AppBlahBlah { /* ... */ }
+//! ```
+//!
+//! # Learn more
+//!
+//! Directory [./examples] contains more advanced usage examples. You can learn
+//! them along with their documentation.
+//!
+//! If you have any trouble while using this crate, please don't hesitate to
+//! [open a discussion] for help. For feature requests or bug reports, please
+//! [open an issue].
+//!
+//! // TODO: vvvvv Refactoring from here vvvvv
 //!
 //! # Overview of features
 //!
@@ -235,20 +312,22 @@
 //! [^2]: C++ `spdlog` is also planned to remove it in v2.x.
 //!
 //! [spdlog]: https://github.com/gabime/spdlog
+//! [`FileSink`]: crate::sink::FileSink
+//! [`RotatingFileSink`]: crate::sink::RotatingFileSink
+//! [`AsyncPoolSink`]: crate::sink::AsyncPoolSink
 //! [./examples]: https://github.com/SpriteOvO/spdlog-rs/tree/main/spdlog/examples
 //! [open a discussion]: https://github.com/SpriteOvO/spdlog-rs/discussions/new
 //! [open an issue]: https://github.com/SpriteOvO/spdlog-rs/issues/new/choose
+//!
 //! [log crate]: https://crates.io/crates/log
 //! [Asynchronous combined sink]: sink/index.html#asynchronous-combined-sink
 //! [`pattern!`]: crate::formatter::pattern
 //! [`runtime_pattern!`]: crate::formatter::runtime_pattern
 //! [`RuntimePattern`]: crate::formatter::RuntimePattern
 //! [`FullFormatter`]: crate::formatter::FullFormatter
-//! [`RotatingFileSink`]: crate::sink::RotatingFileSink
 //! [`Formatter`]: crate::formatter::Formatter
 //! [`RotationPolicy::Daily`]: crate::sink::RotationPolicy::Daily
 //! [`RotationPolicy::Hourly`]: crate::sink::RotationPolicy::Hourly
-//! [`AsyncPoolSink`]: crate::sink::AsyncPoolSink
 
 // Credits: https://blog.wnut.pw/2020/03/24/documentation-and-unstable-rustdoc-features/
 #![cfg_attr(all(doc, CHANNEL_NIGHTLY), feature(doc_auto_cfg))]