From e178c088c0f72af61626aa5b90310d8ee0cf1fa2 Mon Sep 17 00:00:00 2001
From: Jonathan Johnson <jon@khonsulabs.com>
Date: Sun, 22 Sep 2024 07:38:20 -0700
Subject: [PATCH] Logging tweaks + documentation

Closes #169
---
 CHANGELOG.md |  5 +++++
 src/app.rs   | 51 +++++++++++++++++++++++++++++++++++++++++++++++++--
 src/lib.rs   |  7 +++++++
 src/utils.rs |  2 +-
 4 files changed, 62 insertions(+), 3 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index f4d4eaf..1c5bc91 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -63,6 +63,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - `tracing_subscriber` initialization has been moved to `PendingApp::default()`
   from `Window::run`. This ensures logging is always initialized for all Cushy
   apps.
+- The default logging output has been trimmed to only show errors for wgpu,
+  winit, and naga. Thanks to @bluenote10 for the feedback!
 
 ### Fixed
 
@@ -170,6 +172,9 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - `Window::on_file_drop` is a new callback that is invoked when file drop events
   occur for the window.
 - `Image::opacity` allows rendering the image with a given opacity.
+- `PendingApp::with_tracing` and `PendingApp::initialize_tracing` install
+  Cushy's tracing Subscriber. The default `PendingApp` has tracing initialized,
+  but `PendingApp::new` does not.
 
 
 [139]: https://github.com/khonsulabs/cushy/issues/139
diff --git a/src/app.rs b/src/app.rs
index 655f4d2..8ef0186 100644
--- a/src/app.rs
+++ b/src/app.rs
@@ -14,6 +14,37 @@ use crate::window::WindowHandle;
 use crate::{animation, initialize_tracing};
 
 /// A Cushy application that has not started running yet.
+///
+/// ## Logging/Tracing in Cushy
+///
+/// This type is responsible for initializing Cushy's built-in support for
+/// listening for tracing/log messages by installing a global
+/// `tracing_subcriber` Subscriber.
+///
+/// ### To enable logging/tracing support
+///
+/// Most ways of running a Cushy app will automatically intialize logging
+/// because at some point they call `PendingApp::default()`. The default
+/// behavior is to initialize logging.
+///
+/// When using [`PendingApp::new`] to provide a custom [`AppRuntime`], support
+/// can be enabled using:
+///
+/// - [`with_tracing()`](Self::with_tracing)
+/// - [`initialize_tracing()`](Self::initialize_tracing)
+///
+/// ### Overriding Cushy's logging/tracing support
+///
+/// Cushy uses `tracing_subscriber`'s `try_init()` function to install the
+/// global subscriber. This function keeps the existing subscriber if one is
+/// already installed. This means to use your own Subscriber, install it before
+/// calling any Cushy code and your subscriber will be the one used.
+///
+/// ### Disabling tracing support
+///
+/// The `tracing-output` Cargo feature controls whether tracing is enabled. It
+/// is included in `default-features`, but can be omitted to disable tracing
+/// support.
 pub struct PendingApp {
     app: kludgine::app::PendingApp<WindowCommand>,
     cushy: Cushy,
@@ -21,6 +52,11 @@ pub struct PendingApp {
 
 impl PendingApp {
     /// Returns a new app using the provided runtime.
+    ///
+    /// Unliked `PendingApp::default()`, this function does not initialize
+    /// `tracing` support. See
+    /// [`with_tracing()`](Self::with_tracing)/[`initialize_tracing()`](Self::initialize_tracing)
+    /// to enable Cushy's built-in trace handling.
     pub fn new<Runtime: AppRuntime>(runtime: Runtime) -> Self {
         Self {
             app: kludgine::app::PendingApp::default(),
@@ -28,6 +64,18 @@ impl PendingApp {
         }
     }
 
+    /// Installs a global `tracing` Subscriber and returns self.
+    #[must_use]
+    pub fn with_tracing(self) -> Self {
+        self.initialize_tracing();
+        self
+    }
+
+    /// Installs a global `tracing` Subscriber.
+    pub fn initialize_tracing(&self) {
+        initialize_tracing();
+    }
+
     /// The shared resources this application utilizes.
     #[must_use]
     pub const fn cushy(&self) -> &Cushy {
@@ -73,8 +121,7 @@ impl Run for PendingApp {
 
 impl Default for PendingApp {
     fn default() -> Self {
-        initialize_tracing();
-        Self::new(DefaultRuntime::default())
+        Self::new(DefaultRuntime::default()).with_tracing()
     }
 }
 
diff --git a/src/lib.rs b/src/lib.rs
index 182d16e..b86c7bc 100644
--- a/src/lib.rs
+++ b/src/lib.rs
@@ -133,6 +133,7 @@ use figures::units::UPx;
 use figures::{Fraction, ScreenUnit, Size, Zero};
 use kludgine::app::winit::error::EventLoopError;
 pub use names::Name;
+use tracing_subscriber::filter::Targets;
 pub use utils::{Lazy, ModifiersExt, ModifiersStateExt, WithClone};
 pub use {figures, kludgine};
 
@@ -311,6 +312,12 @@ fn initialize_tracing() {
                     .with_default_directive(LevelFilter::from_level(MAX_LEVEL).into())
                     .from_env_lossy(),
             )
+            .with(
+                Targets::new()
+                    .with_target("winit", Level::ERROR)
+                    .with_target("wgpu", Level::ERROR)
+                    .with_target("naga", Level::ERROR),
+            )
             .try_init();
     }
 }
diff --git a/src/utils.rs b/src/utils.rs
index 36ce831..03d515c 100644
--- a/src/utils.rs
+++ b/src/utils.rs
@@ -74,7 +74,7 @@ impl_all_tuples!(impl_with_clone);
 pub trait ModifiersStateExt {
     /// The modifier key used for shortcuts.
     ///
-    /// For Apple based platforms, this is [`ModifierState::SUPER`]. This
+    /// For Apple based platforms, this is [`ModifiersState::SUPER`]. This
     /// corresponds to the Apple/Command key.
     ///
     /// For all other platforms, this is [`ModifiersState::CONTROL`].