Update documentation for Level and LevelFilter

Author: str4d

crates/flipperzero/src/furi/log/metadata.rs

@@ -7,7 +7,7 @@ use core::{cmp, fmt, str::FromStr};
 
 use flipperzero_sys as sys;
 
-/// Describes the level of verbosity of a span or event.
+/// Describes the level of verbosity of a log message.
 ///
 /// # Comparing Levels
 ///
@@ -19,7 +19,7 @@ use flipperzero_sys as sys;
 ///
 /// For example:
 /// ```
-/// use tracing_core::Level;
+/// use flipperzero::furi::log::Level;
 ///
 /// assert!(Level::TRACE > Level::DEBUG);
 /// assert!(Level::ERROR < Level::WARN);
@@ -30,25 +30,25 @@ use flipperzero_sys as sys;
 /// # Filtering
 ///
 /// `Level`s are typically used to implement filtering that determines which
-/// spans and events are enabled. Depending on the use case, more or less
+/// log messages are enabled. Depending on the use case, more or less
 /// verbose diagnostics may be desired. For example, when running in
-/// development, [`DEBUG`]-level traces may be enabled by default. When running in
-/// production, only [`INFO`]-level and lower traces might be enabled. Libraries
+/// development, [`DEBUG`]-level logs may be enabled by default. When running in
+/// production, only [`INFO`]-level and lower logs might be enabled. Libraries
 /// may include very verbose diagnostics at the [`DEBUG`] and/or [`TRACE`] levels.
-/// Applications using those libraries typically chose to ignore those traces. However, when
+/// Applications using those libraries typically chose to ignore those logs. However, when
 /// debugging an issue involving said libraries, it may be useful to temporarily
-/// enable the more verbose traces.
+/// enable the more verbose logs.
 ///
-/// The [`LevelFilter`] type is provided to enable filtering traces by
+/// The [`LevelFilter`] type is provided to enable filtering logs by
 /// verbosity. `Level`s can be compared against [`LevelFilter`]s, and
 /// [`LevelFilter`] has a variant for each `Level`, which compares analogously
 /// to that level. In addition, [`LevelFilter`] adds a [`LevelFilter::OFF`]
 /// variant, which is considered "less verbose" than every other `Level`. This is
-/// intended to allow filters to completely disable tracing in a particular context.
+/// intended to allow filters to completely disable logging in a particular context.
 ///
 /// For example:
 /// ```
-/// use tracing_core::{Level, LevelFilter};
+/// use flipperzero::furi::log::{Level, LevelFilter};
 ///
 /// assert!(LevelFilter::OFF < Level::TRACE);
 /// assert!(LevelFilter::TRACE > Level::DEBUG);
@@ -59,83 +59,15 @@ use flipperzero_sys as sys;
 ///
 /// ## Examples
 ///
-/// Below is a simple example of how a [collector] could implement filtering through
-/// a [`LevelFilter`]. When a span or event is recorded, the [`Collect::enabled`] method
-/// compares the span or event's `Level` against the configured [`LevelFilter`].
-/// The optional [`Collect::max_level_hint`] method can also be implemented to  allow spans
-/// and events above a maximum verbosity level to be skipped more efficiently,
-/// often improving performance in short-lived programs.
-///
-/// ```
-/// use tracing_core::{span, Event, Level, LevelFilter, Collect, Metadata};
-/// # use tracing_core::span::{Id, Record, Current};
-///
-/// #[derive(Debug)]
-/// pub struct MyCollector {
-///     /// The most verbose level that this collector will enable.
-///     max_level: LevelFilter,
-///
-///     // ...
-/// }
-///
-/// impl MyCollector {
-///     /// Returns a new `MyCollector` which will record spans and events up to
-///     /// `max_level`.
-///     pub fn with_max_level(max_level: LevelFilter) -> Self {
-///         Self {
-///             max_level,
-///             // ...
-///         }
-///     }
-/// }
-/// impl Collect for MyCollector {
-///     fn enabled(&self, meta: &Metadata<'_>) -> bool {
-///         // A span or event is enabled if it is at or below the configured
-///         // maximum level.
-///         meta.level() <= &self.max_level
-///     }
-///
-///     // This optional method returns the most verbose level that this
-///     // collector will enable. Although implementing this method is not
-///     // *required*, it permits additional optimizations when it is provided,
-///     // allowing spans and events above the max level to be skipped
-///     // more efficiently.
-///     fn max_level_hint(&self) -> Option<LevelFilter> {
-///         Some(self.max_level)
-///     }
-///
-///     // Implement the rest of the collector...
-///     fn new_span(&self, span: &span::Attributes<'_>) -> span::Id {
-///         // ...
-///         # drop(span); Id::from_u64(1)
-///     }
-
-///     fn event(&self, event: &Event<'_>) {
-///         // ...
-///         # drop(event);
-///     }
-///
-///     // ...
-///     # fn enter(&self, _: &Id) {}
-///     # fn exit(&self, _: &Id) {}
-///     # fn record(&self, _: &Id, _: &Record<'_>) {}
-///     # fn record_follows_from(&self, _: &Id, _: &Id) {}
-///     # fn current_span(&self) -> Current { Current::unknown() }
-/// }
-/// ```
-///
-/// It is worth noting that the `tracing-subscriber` crate provides [additional
-/// APIs][envfilter] for performing more sophisticated filtering, such as
-/// enabling different levels based on which module or crate a span or event is
-/// recorded in.
+/// `Level` should generally be used with the [`log`] macro via its associated
+/// constants. You can also use the helper macros like [`warn`] directly without
+/// needing to specify a `Level`.
 ///
 /// [`DEBUG`]: Level::DEBUG
 /// [`INFO`]: Level::INFO
 /// [`TRACE`]: Level::TRACE
-/// [`Collect::enabled`]: crate::collect::Collect::enabled
-/// [`Collect::max_level_hint`]: crate::collect::Collect::max_level_hint
-/// [collector]: crate::collect::Collect
-/// [envfilter]: https://docs.rs/tracing-subscriber/latest/tracing_subscriber/filter/struct.EnvFilter.html
+/// [`log`]: crate::log
+/// [`warn`]: crate::warn
 #[derive(Copy, Clone, Debug, PartialEq, Eq, Hash, PartialOrd, Ord)]
 pub struct Level(LevelInner);
 
@@ -147,7 +79,7 @@ pub struct Level(LevelInner);
 /// details.
 ///
 /// Note that this is essentially identical to the `Level` type, but with the
-/// addition of an [`OFF`] level that completely disables all trace
+/// addition of an [`OFF`] level that completely disables all logging
 /// instrumentation.
 ///
 /// See the documentation for the [`Level`] type to see how `Level`s
@@ -308,7 +240,7 @@ impl LevelFilter {
     /// Designates very low priority, often extremely verbose, information.
     pub const TRACE: LevelFilter = LevelFilter::from_level(Level::TRACE);
 
-    /// Returns a `LevelFilter` that enables spans and events with verbosity up
+    /// Returns a `LevelFilter` that enables log messages with verbosity up
     /// to and including `level`.
     pub const fn from_level(level: Level) -> Self {
         Self(match level.0 {
@@ -336,22 +268,21 @@ impl LevelFilter {
         }
     }
 
-    /// Returns a `LevelFilter` that matches the most verbose [`Level`] that any
-    /// currently active [collector] will enable.
+    /// Returns a `LevelFilter` that matches the most verbose [`Level`] that the
+    /// Furi Logging system will enable.
     ///
-    /// User code should treat this as a *hint*. If a given span or event has a
+    /// User code should treat this as a *hint*. If a given log message has a
     /// level *higher* than the returned `LevelFilter`, it will not be enabled.
-    /// However, if the level is less than or equal to this value, the span or
-    /// event is *not* guaranteed to be enabled; the collector will still
-    /// filter each callsite individually.
+    /// However, if the level is less than or equal to this value, the log
+    /// message is *not* guaranteed to be enabled; the Furi Logging system may
+    /// perform additional filtering.
     ///
-    /// Therefore, comparing a given span or event's level to the returned
+    /// Therefore, comparing a given log message's level to the returned
     /// `LevelFilter` **can** be used for determining if something is
     /// *disabled*, but **should not** be used for determining if something is
     /// *enabled*.
     ///
     /// [`Level`]: super::Level
-    /// [collector]: super::Collect
     #[inline(always)]
     pub fn current() -> Self {
         match unsafe { sys::furi_log_get_level() } {