docs(stackable-telemetry): Partially add docs

Note: More docs will appear in a future PR so that this PR isn't a blocker.

Tip: Enable `#![warn(missing_docs)]`

Author: NickLarsenNZ

crates/stackable-telemetry/src/tracing/settings/console_log.rs

@@ -1,21 +1,41 @@
+//! Console Log Subscriber Settings.
+
 use tracing::level_filters::LevelFilter;
 
 use super::{Build, CommonSettings, Settings, SettingsBuilder};
 
+/// Configure specific settings for the Console Log subscriber.
 #[derive(Debug, Default, PartialEq)]
 pub struct ConsoleLogSettings {
+    /// Common subscriber settings that apply to the Console Log Subscriber.
     pub common_settings: Settings,
+
+    /// Console Subscriber log event output format.
     pub log_format: Format,
 }
 
+/// Console Subscriber log event output formats.
+///
+/// Currently, only [Plain][Format::Plain] is supported.
 #[derive(Debug, Default, PartialEq)]
 pub enum Format {
+    /// Use the plain unstructured log output.
+    ///
+    /// ANSI color output is enabled by default, but can be disabled at runtime by
+    /// setting `NO_COLOR` to a non-empty value.
+    ///
+    /// See: [`Layer::with_ansi`][tracing_subscriber::fmt::Layer::with_ansi].
     #[default]
     Plain,
     // Json { pretty: bool },
     // LogFmt,
 }
 
+/// For building [`ConsoleLogSettings`].
+///
+/// <div class="warning">
+/// Do not use directly, instead use the [`Settings::builder`] associated function.
+/// </div>
 pub struct ConsoleLogSettingsBuilder {
     pub(crate) common_settings: Settings,
     pub(crate) log_format: Format,

crates/stackable-telemetry/src/tracing/settings/mod.rs

@@ -1,3 +1,5 @@
+//! Subscriber settings.
+
 use tracing::level_filters::LevelFilter;
 
 pub mod console_log;
@@ -9,23 +11,40 @@ pub use otlp_log::*;
 pub mod otlp_trace;
 pub use otlp_trace::*;
 
-// this trait is to make it simpler to access common settings from specific settings.
+/// Simplifies access common settings from subscriber specific settings.
 pub trait CommonSettings {
+    /// Access to the [`Settings::environment_variable`] field.
     fn environment_variable(&self) -> &'static str;
+
+    /// Access to the [`Settings::default_level`] field.
     fn default_level(&self) -> LevelFilter;
+
+    /// Access to the [`Settings::enabled`] field.
     fn enabled(&self) -> bool;
 }
 
+/// General settings that apply to any subscriber.
 #[derive(Debug, PartialEq)]
 pub struct Settings {
+    /// The environment variable used to set the [`LevelFilter`].
+    ///
+    /// When the environment variable is set, it will override what is set by
+    /// [`Self::default_level`].
     pub environment_variable: &'static str,
 
+    /// The [`LevelFilter`] to fallback to if [`Self::environment_variable`] has
+    /// not been set.
     pub default_level: LevelFilter,
 
+    /// Whether or not the subscriber is enabled.
+    ///
+    /// When set to `true`, the [`tracing::Subscriber`] will be added to the
+    /// [`tracing_subscriber::Layer`] list.
     pub enabled: bool,
 }
 
 impl Settings {
+    /// Builder methods to override defaults.
     pub fn builder() -> SettingsBuilder {
         SettingsBuilder::default()
     }
@@ -37,13 +56,16 @@ impl Default for Settings {
     }
 }
 
+/// For building [`Settings`].
 pub struct SettingsBuilder {
     environment_variable: &'static str,
     enabled: bool,
     default_level: LevelFilter,
 }
 
+/// Finalizer to be implemented on builders.
 pub trait Build<T> {
+    /// Finalize settings.
     fn build(self) -> T;
 }
 
@@ -54,16 +76,27 @@ impl Build<Settings> for SettingsBuilder {
 }
 
 impl SettingsBuilder {
+    /// Set the environment variable used for overriding the [`Settings::default_level`].
+    ///
+    /// Defaults to `RUST_LOG`.
+    // TODO (@NickLarsenNZ): set a constant for the default environment variable.
     pub fn with_environment_variable(mut self, name: &'static str) -> Self {
         self.environment_variable = name;
         self
     }
 
+    /// Set the default [`LevelFilter`].
+    ///
+    /// Defaults to [`LevelFilter::OFF`].
+    // TODO (@NickLarsenNZ): set a constant for the default level.
     pub fn with_default_level(mut self, level: impl Into<LevelFilter>) -> Self {
         self.default_level = level.into();
         self
     }
 
+    /// Enable or disable the [`tracing::Subscriber`].
+    ///
+    /// Defaults to `false`.
     // TODO (@NickLarsenNZ): Currently this has to be called to enable the
     // subscriber. Eventually it should become optional, and default to on (if
     // settings are supplied). Therefore, the fields in TracingBuilder to hold
@@ -75,14 +108,17 @@ impl SettingsBuilder {
         self
     }
 
+    /// Set specific [`ConsoleLogSettings`].
     pub fn console_log_settings_builder(self) -> ConsoleLogSettingsBuilder {
         self.into()
     }
 
+    /// Set specific [`OtlpLogSettings`].
     pub fn otlp_log_settings_builder(self) -> OtlpLogSettingsBuilder {
         self.into()
     }
 
+    /// Set specific [`OtlpTraceSettings`].
     pub fn otlp_trace_settings_builder(self) -> OtlpTraceSettingsBuilder {
         self.into()
     }

crates/stackable-telemetry/src/tracing/settings/otlp_log.rs

@@ -1,3 +1,5 @@
+//! OTLP Log Subscriber Settings.
+
 use tracing::level_filters::LevelFilter;
 
 use super::{Build, CommonSettings, Settings, SettingsBuilder};

crates/stackable-telemetry/src/tracing/settings/otlp_trace.rs

@@ -1,3 +1,5 @@
+//! OTLP Trace Subscriber Settings.
+
 use tracing::level_filters::LevelFilter;
 
 use super::{Build, CommonSettings, Settings, SettingsBuilder};