Add documentation for the runtime_pattern macro

spdlog/src/formatter/pattern_formatter/runtime.rs

@@ -14,9 +14,40 @@ type PatternCreator = Box<dyn Fn() -> Box<dyn Pattern>>;
 type PatternRegistry = GenericPatternRegistry<PatternCreator>;
 type PatternKind = GenericPatternKind<PatternCreator>;
 
-/// Construct a runtime pattern.
+/// Build a runtime pattern.
 ///
-/// TODO: add detailed documentation for runtime_pattern.
+/// It accepts inputs in the form:
+///
+/// ```ignore
+/// // This is not exactly a valid declarative macro, just for intuition.
+/// macro_rules! pattern {
+///     ( $template:expr $(,)? ) => {};
+///     ( $template:expr, $( {$$custom:ident} => $ctor:expr ),+ $(,)? ) => {};
+/// }
+/// ```
+///
+/// The only difference between `runtime_pattern` and [`pattern`] is that
+/// `pattern` only accepts a string literal as the pattern template, while
+/// `runtime_pattern` accepts an expression that will be evaluated to the
+/// pattern template string at runtime.
+///
+/// [`pattern`]: crate::formatter::pattern
+///
+/// `runtime_pattern` will expand to an expression of type
+/// `Result<RuntimePattern, spdlog::error::Error>`. The expanded expression
+/// will evaluate to an error value when parsing of the pattern template
+/// string at runtime fails. If any of the custom patterns given are invalid,
+/// this macro will trigger a compilation error.
+///
+/// ```
+/// use spdlog::formatter::{pattern, PatternFormatter};
+///
+/// let template = String::from("[{level}] {payload} - {$mypat}{eol}");
+/// let pat = runtime_pattern!(template,
+///     {$mypat} => MyPattern::default,
+/// ).unwrap();
+/// let formatter = PatternFormatter::new(pat);
+/// ```
 pub use spdlog_macros::runtime_pattern;
 
 #[rustfmt::skip] // rustfmt currently breaks some empty lines if `#[doc = include_str!("xxx")]` exists