docs(stackable-telemetry): Add #![warn(missing_docs)] (#944)

* docs(stackable-telemetry): Add #![warn(missing_docs)]

* chore: Apply suggestions

Co-authored-by: Siegfried Weber <[email protected]>

* chore: Apply suggestion

Co-authored-by: Siegfried Weber <[email protected]>

---------

Co-authored-by: Siegfried Weber <[email protected]>

Author: Techassi

crates/stackable-telemetry/src/instrumentation/axum/mod.rs

@@ -173,20 +173,34 @@ where
     }
 }
 
+/// Errors which can be encountered when extracting the server host from a [`Request`].
 #[derive(Debug, Snafu)]
 pub enum ServerHostError {
+    /// Indicates that parsing the port of the server host from the [`Request`] as a `u16` failed.
     #[snafu(display("failed to parse port {port:?} as u16 from string"))]
-    ParsePort { source: ParseIntError, port: String },
+    ParsePort {
+        #[allow(missing_docs)]
+        source: ParseIntError,
 
+        // TODO (@Techassi): Make snafu re-emit this
+        /// The original input which was attempted to be parsed.
+        port: String,
+    },
+
+    /// Indicates that the server host from the [`Request`] contains an invalid/unknown scheme.
     #[snafu(display("encountered invalid request scheme {scheme:?}"))]
-    InvalidScheme { scheme: String },
+    InvalidScheme {
+        /// The original scheme.
+        scheme: String,
+    },
 
+    // TODO (@Techassi): Make snafu re-emit this
+    /// Indicates that no method of extracting the server host from the [`Request`] succeeded.
     #[snafu(display("failed to extract any host information from request"))]
     ExtractHost,
 }
 
-/// This trait provides various helper functions to extract data from a
-/// HTTP [`Request`].
+/// This trait provides various helper functions to extract data from a HTTP [`Request`].
 pub trait RequestExt {
     /// Returns the client socket address, if available.
     fn client_socket_address(&self) -> Option<SocketAddr>;
@@ -429,7 +443,7 @@ impl SpanExt for Span {
         // Therefore, we have to made a decision about linking the two traces.
         // These are the options:
         // 1. Link to the trace id supplied in the incoming request, or
-        // 2. Link to the current trace id, then set the parent contex based on
+        // 2. Link to the current trace id, then set the parent context based on
         //    trace information supplied in the incoming request.
         //
         // Neither is ideal, as it means there are (at least) two traces to look

crates/stackable-telemetry/src/lib.rs

@@ -1,5 +1,7 @@
-//! This crate contains various Tracing, Logging, and OpenTelemtry primitives to
-//! easily instrument code.
+#![warn(missing_docs)]
+
+//! This crate contains various Tracing, Logging, and OpenTelemetry primitives to easily instrument
+//! code.
 pub mod instrumentation;
 pub mod tracing;
 

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

@@ -25,23 +25,36 @@ pub mod settings;
 
 type Result<T, E = Error> = std::result::Result<T, E>;
 
+/// Errors which can be encountered when initialising [`Tracing`].
 #[derive(Debug, Snafu)]
 pub enum Error {
+    /// Indicates that [`Tracing`] failed to install the OpenTelemetry trace exporter.
     #[snafu(display("unable to install opentelemetry trace exporter"))]
     InstallOtelTraceExporter {
+        #[allow(missing_docs)]
         source: opentelemetry::trace::TraceError,
     },
 
+    /// Indicates that [`Tracing`] failed to install the OpenTelemetry log exporter.
     #[snafu(display("unable to install opentelemetry log exporter"))]
     InstallOtelLogExporter {
+        #[allow(missing_docs)]
         source: opentelemetry::logs::LogError,
     },
 
-    #[snafu(display("unable to set the global default subscriber"))]
-    SetGlobalDefaultSubscriber { source: SetGlobalDefaultError },
-
+    /// Indicates that [`Tracing`] failed to install the rolling file appender.
     #[snafu(display("failed to initialize rolling file appender"))]
-    InitRollingFileAppender { source: InitError },
+    InitRollingFileAppender {
+        #[allow(missing_docs)]
+        source: InitError,
+    },
+
+    /// Indicates that [`Tracing`] failed to set the global default subscriber.
+    #[snafu(display("unable to set the global default subscriber"))]
+    SetGlobalDefaultSubscriber {
+        #[allow(missing_docs)]
+        source: SetGlobalDefaultError,
+    },
 }
 
 /// Easily initialize a set of pre-configured [`Subscriber`][1] layers.
@@ -225,6 +238,7 @@ pub struct Tracing {
 }
 
 impl Tracing {
+    /// Creates and returns a [`TracingBuilder`].
     pub fn builder() -> TracingBuilder<builder_state::PreServiceName> {
         TracingBuilder::default()
     }

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

@@ -6,13 +6,13 @@ use tracing::level_filters::LevelFilter;
 
 use super::{Settings, SettingsBuilder};
 
-/// Configure specific settings for the Console Log subscriber.
+/// 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.
+    /// Common subscriber settings that apply to the console log subscriber.
     pub common_settings: Settings,
 
-    /// Console Subscriber log event output format.
+    /// Console subscriber log event output format.
     pub log_format: Format,
 }
 
@@ -24,7 +24,7 @@ impl Deref for ConsoleLogSettings {
     }
 }
 
-/// Console Subscriber log event output formats.
+/// Console subscriber log event output formats.
 ///
 /// Currently, only [Plain][Format::Plain] is supported.
 #[derive(Debug, Default, PartialEq)]
@@ -52,11 +52,13 @@ pub struct ConsoleLogSettingsBuilder {
 }
 
 impl ConsoleLogSettingsBuilder {
+    /// Overrides the default log [`Format`].
     pub fn with_log_format(mut self, format: Format) -> Self {
         self.log_format = format;
         self
     }
 
+    /// Consumes `self` and builds [`ConsoleLogSettings`].
     pub fn build(self) -> ConsoleLogSettings {
         ConsoleLogSettings {
             common_settings: self.common_settings,

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

@@ -6,8 +6,10 @@ use tracing::level_filters::LevelFilter;
 
 use super::{Settings, SettingsBuilder};
 
+/// Configure specific settings for the OpenTelemetry log subscriber.
 #[derive(Debug, Default, PartialEq)]
 pub struct OtlpLogSettings {
+    /// Common subscriber settings that apply to the OpenTelemetry log subscriber.
     pub common_settings: Settings,
 }
 
@@ -19,11 +21,19 @@ impl Deref for OtlpLogSettings {
     }
 }
 
+/// For building [`OtlpLogSettings`].
+///
+/// <div class="warning">
+///
+/// Do not use directly, instead use the [`Settings::builder`] associated function.
+///
+/// </div>
 pub struct OtlpLogSettingsBuilder {
     pub(crate) common_settings: Settings,
 }
 
 impl OtlpLogSettingsBuilder {
+    /// Consumes `self` and builds [`OtlpLogSettings`].
     pub fn build(self) -> OtlpLogSettings {
         OtlpLogSettings {
             common_settings: self.common_settings,

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

@@ -6,8 +6,10 @@ use tracing::level_filters::LevelFilter;
 
 use super::{Settings, SettingsBuilder};
 
+/// Configure specific settings for the OpenTelemetry trace subscriber.
 #[derive(Debug, Default, PartialEq)]
 pub struct OtlpTraceSettings {
+    /// Common subscriber settings that apply to the OpenTelemetry trace subscriber.
     pub common_settings: Settings,
 }
 
@@ -19,11 +21,19 @@ impl Deref for OtlpTraceSettings {
     }
 }
 
+/// For building [`OtlpTraceSettings`].
+///
+/// <div class="warning">
+///
+/// Do not use directly, instead use the [`Settings::builder`] associated function.
+///
+/// </div>
 pub struct OtlpTraceSettingsBuilder {
     pub(crate) common_settings: Settings,
 }
 
 impl OtlpTraceSettingsBuilder {
+    /// Consumes `self` and builds [`OtlpTraceSettings`].
     pub fn build(self) -> OtlpTraceSettings {
         OtlpTraceSettings {
             common_settings: self.common_settings,