From c3fb62986119879a7f140ce4e2b44e18290bfde8 Mon Sep 17 00:00:00 2001
From: Jos Feenstra <me@josfeenstra.nl>
Date: Wed, 29 Nov 2023 19:59:16 +0100
Subject: [PATCH 01/10] add macro to log only once per callsite

---
 crates/bevy_log/src/lib.rs  |  4 ++
 crates/bevy_log/src/once.rs | 74 +++++++++++++++++++++++++++++++++++++
 2 files changed, 78 insertions(+)
 create mode 100644 crates/bevy_log/src/once.rs

diff --git a/crates/bevy_log/src/lib.rs b/crates/bevy_log/src/lib.rs
index cc8d3e7a47100..bab058535e4c2 100644
--- a/crates/bevy_log/src/lib.rs
+++ b/crates/bevy_log/src/lib.rs
@@ -11,6 +11,8 @@
 //! For more fine-tuned control over logging behavior, set up the [`LogPlugin`] or
 //! `DefaultPlugins` during app initialization.
 
+mod once;
+
 #[cfg(feature = "trace")]
 use std::panic;
 
@@ -28,6 +30,8 @@ pub mod prelude {
     pub use bevy_utils::tracing::{
         debug, debug_span, error, error_span, info, info_span, trace, trace_span, warn, warn_span,
     };
+
+    pub use crate::{debug_once, error_once, info_once, trace_once, warn_once};
 }
 
 pub use bevy_utils::tracing::{
diff --git a/crates/bevy_log/src/once.rs b/crates/bevy_log/src/once.rs
new file mode 100644
index 0000000000000..9b8b5bca91b57
--- /dev/null
+++ b/crates/bevy_log/src/once.rs
@@ -0,0 +1,74 @@
+/// Call `trace!(...)` once per call site.
+///
+/// Useful for logging within systems which are called every frame.
+#[macro_export]
+macro_rules! trace_once {
+    ($($arg:tt)+) => ({
+        use ::std::sync::atomic::{AtomicBool, Ordering};
+
+        static FIRST_TIME: AtomicBool = AtomicBool::new(true);
+        if FIRST_TIME.swap(false, Ordering::Relaxed) {
+            trace!("{}", format!($($arg)+));
+        }
+    });
+}
+
+/// Call `debug!(...)` once per call site.
+///
+/// Useful for logging within systems which are called every frame.
+#[macro_export]
+macro_rules! debug_once {
+    ($($arg:tt)+) => ({
+        use ::std::sync::atomic::{AtomicBool, Ordering};
+
+        static FIRST_TIME: AtomicBool = AtomicBool::new(true);
+        if FIRST_TIME.swap(false, Ordering::Relaxed) {
+            debug!("{}", format!($($arg)+));
+        }
+    });
+}
+
+/// Call `info!(...)` once per call site.
+///
+/// Useful for logging within systems which are called every frame.
+#[macro_export]
+macro_rules! info_once {
+    ($($arg:tt)+) => ({
+        use ::std::sync::atomic::{AtomicBool, Ordering};
+
+        static FIRST_TIME: AtomicBool = AtomicBool::new(true);
+        if FIRST_TIME.swap(false, Ordering::Relaxed) {
+            info!("{}", format!($($arg)+));
+        }
+    });
+}
+
+/// Call `warn!(...)` once per call site.
+///
+/// Useful for logging within systems which are called every frame.
+#[macro_export]
+macro_rules! warn_once {
+    ($($arg:tt)+) => ({
+        use ::std::sync::atomic::{AtomicBool, Ordering};
+
+        static FIRST_TIME: AtomicBool = AtomicBool::new(true);
+        if FIRST_TIME.swap(false, Ordering::Relaxed) {
+            warn!("{}", format!($($arg)+));
+        }
+    });
+}
+
+/// Call `error!(...)` once per call site.
+///
+/// Useful for logging within systems which are called every frame.
+#[macro_export]
+macro_rules! error_once {
+    ($($arg:tt)+) => ({
+        use ::std::sync::atomic::{AtomicBool, Ordering};
+
+        static FIRST_TIME: AtomicBool = AtomicBool::new(true);
+        if FIRST_TIME.swap(false, Ordering::Relaxed) {
+            error!("{}", format!($($arg)+));
+        }
+    });
+}

From ac8a494ccf0d6f3ffebe85192ba627b7a3f32e6f Mon Sep 17 00:00:00 2001
From: Jos Feenstra <me@josfeenstra.nl>
Date: Wed, 29 Nov 2023 19:59:21 +0100
Subject: [PATCH 02/10] add example

---
 examples/app/logs.rs | 16 ++++++++++++++++
 1 file changed, 16 insertions(+)

diff --git a/examples/app/logs.rs b/examples/app/logs.rs
index 17fd51dfda46e..b588e78becfb0 100644
--- a/examples/app/logs.rs
+++ b/examples/app/logs.rs
@@ -11,6 +11,7 @@ fn main() {
             ..default()
         }))
         .add_systems(Update, log_system)
+        .add_systems(Update, log_once_system)
         .run();
 }
 
@@ -30,3 +31,18 @@ fn log_system() {
     // the format used here is super flexible. check out this documentation for more info:
     // https://docs.rs/tracing-subscriber/*/tracing_subscriber/filter/struct.EnvFilter.html
 }
+
+fn log_once_system() {
+    // The 'once' variants of each log level are useful when a system is called every frame,
+    // but we still wish to inform the user only once. In other words, use these to prevent spam :)
+
+    trace_once!("one time noisy message");
+    debug_once!("one time debug message");
+    info_once!("some info which is printed only once");
+    warn_once!("some warning we wish to call out only once");
+    error_once!("some error we wish to report only once");
+
+    for i in 0..10 {
+        error_once!("logs once per call site, so this works just fine: {}", i);
+    }
+}

From c0785cf59e7c33514edb2e91b6bf603e6d3473ef Mon Sep 17 00:00:00 2001
From: Jos Feenstra <me@josfeenstra.nl>
Date: Wed, 29 Nov 2023 21:05:24 +0100
Subject: [PATCH 03/10] remove unneeded `format!()`. return boolean to express
 internal state

---
 crates/bevy_log/src/once.rs | 35 ++++++++++++++++++++++++++++++-----
 examples/app/logs.rs        |  6 +++++-
 2 files changed, 35 insertions(+), 6 deletions(-)

diff --git a/crates/bevy_log/src/once.rs b/crates/bevy_log/src/once.rs
index 9b8b5bca91b57..05e046f265e8a 100644
--- a/crates/bevy_log/src/once.rs
+++ b/crates/bevy_log/src/once.rs
@@ -1,6 +1,8 @@
 /// Call `trace!(...)` once per call site.
 ///
 /// Useful for logging within systems which are called every frame.
+///
+/// Returns true the first time this is called
 #[macro_export]
 macro_rules! trace_once {
     ($($arg:tt)+) => ({
@@ -8,7 +10,10 @@ macro_rules! trace_once {
 
         static FIRST_TIME: AtomicBool = AtomicBool::new(true);
         if FIRST_TIME.swap(false, Ordering::Relaxed) {
-            trace!("{}", format!($($arg)+));
+            trace!($($arg)+);
+            true
+        } else {
+            false
         }
     });
 }
@@ -16,6 +21,8 @@ macro_rules! trace_once {
 /// Call `debug!(...)` once per call site.
 ///
 /// Useful for logging within systems which are called every frame.
+///
+/// Returns true the first time this is called
 #[macro_export]
 macro_rules! debug_once {
     ($($arg:tt)+) => ({
@@ -23,7 +30,10 @@ macro_rules! debug_once {
 
         static FIRST_TIME: AtomicBool = AtomicBool::new(true);
         if FIRST_TIME.swap(false, Ordering::Relaxed) {
-            debug!("{}", format!($($arg)+));
+            debug!($($arg)+);
+            true
+        } else {
+            false
         }
     });
 }
@@ -31,6 +41,8 @@ macro_rules! debug_once {
 /// Call `info!(...)` once per call site.
 ///
 /// Useful for logging within systems which are called every frame.
+///
+/// Returns true the first time this is called
 #[macro_export]
 macro_rules! info_once {
     ($($arg:tt)+) => ({
@@ -38,7 +50,10 @@ macro_rules! info_once {
 
         static FIRST_TIME: AtomicBool = AtomicBool::new(true);
         if FIRST_TIME.swap(false, Ordering::Relaxed) {
-            info!("{}", format!($($arg)+));
+            info!($($arg)+);
+            true
+        } else {
+            false
         }
     });
 }
@@ -46,6 +61,8 @@ macro_rules! info_once {
 /// Call `warn!(...)` once per call site.
 ///
 /// Useful for logging within systems which are called every frame.
+///
+/// Returns true the first time this is called
 #[macro_export]
 macro_rules! warn_once {
     ($($arg:tt)+) => ({
@@ -53,7 +70,10 @@ macro_rules! warn_once {
 
         static FIRST_TIME: AtomicBool = AtomicBool::new(true);
         if FIRST_TIME.swap(false, Ordering::Relaxed) {
-            warn!("{}", format!($($arg)+));
+            warn!($($arg)+);
+            true
+        } else {
+            false
         }
     });
 }
@@ -61,6 +81,8 @@ macro_rules! warn_once {
 /// Call `error!(...)` once per call site.
 ///
 /// Useful for logging within systems which are called every frame.
+///
+/// Returns true the first time this is called
 #[macro_export]
 macro_rules! error_once {
     ($($arg:tt)+) => ({
@@ -68,7 +90,10 @@ macro_rules! error_once {
 
         static FIRST_TIME: AtomicBool = AtomicBool::new(true);
         if FIRST_TIME.swap(false, Ordering::Relaxed) {
-            error!("{}", format!($($arg)+));
+            info!($($arg)+);
+            true
+        } else {
+            false
         }
     });
 }
diff --git a/examples/app/logs.rs b/examples/app/logs.rs
index b588e78becfb0..41410469ce78a 100644
--- a/examples/app/logs.rs
+++ b/examples/app/logs.rs
@@ -43,6 +43,10 @@ fn log_once_system() {
     error_once!("some error we wish to report only once");
 
     for i in 0..10 {
-        error_once!("logs once per call site, so this works just fine: {}", i);
+        info_once!("logs once per call site, so this works just fine: {}", i);
+    }
+
+    if info_once!("some more info") {
+        info!("this is the first and only time 'some more info' was printed");
     }
 }

From 7bdcbd7836df1e0a19950515187328e70588d9d3 Mon Sep 17 00:00:00 2001
From: Jos Feenstra <me@josfeenstra.nl>
Date: Wed, 29 Nov 2023 21:17:25 +0100
Subject: [PATCH 04/10] fix

---
 crates/bevy_log/src/once.rs | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/crates/bevy_log/src/once.rs b/crates/bevy_log/src/once.rs
index 05e046f265e8a..0a0b8222bea18 100644
--- a/crates/bevy_log/src/once.rs
+++ b/crates/bevy_log/src/once.rs
@@ -90,7 +90,7 @@ macro_rules! error_once {
 
         static FIRST_TIME: AtomicBool = AtomicBool::new(true);
         if FIRST_TIME.swap(false, Ordering::Relaxed) {
-            info!($($arg)+);
+            error!($($arg)+);
             true
         } else {
             false

From 6f87d32716f0b4b435c1179a1f658c6734f71169 Mon Sep 17 00:00:00 2001
From: Jos Feenstra <me@josfeenstra.nl>
Date: Thu, 30 Nov 2023 09:41:41 +0100
Subject: [PATCH 05/10] apply mrGVSV's comments

---
 crates/bevy_log/src/once.rs | 20 ++++++++++----------
 1 file changed, 10 insertions(+), 10 deletions(-)

diff --git a/crates/bevy_log/src/once.rs b/crates/bevy_log/src/once.rs
index 0a0b8222bea18..3a76379baf22b 100644
--- a/crates/bevy_log/src/once.rs
+++ b/crates/bevy_log/src/once.rs
@@ -1,4 +1,4 @@
-/// Call `trace!(...)` once per call site.
+/// Call [`trace!`] once per call site.
 ///
 /// Useful for logging within systems which are called every frame.
 ///
@@ -10,7 +10,7 @@ macro_rules! trace_once {
 
         static FIRST_TIME: AtomicBool = AtomicBool::new(true);
         if FIRST_TIME.swap(false, Ordering::Relaxed) {
-            trace!($($arg)+);
+            $crate::trace!($($arg)+);
             true
         } else {
             false
@@ -18,7 +18,7 @@ macro_rules! trace_once {
     });
 }
 
-/// Call `debug!(...)` once per call site.
+/// Call [`debug!`] once per call site.
 ///
 /// Useful for logging within systems which are called every frame.
 ///
@@ -30,7 +30,7 @@ macro_rules! debug_once {
 
         static FIRST_TIME: AtomicBool = AtomicBool::new(true);
         if FIRST_TIME.swap(false, Ordering::Relaxed) {
-            debug!($($arg)+);
+            $crate::debug!($($arg)+);
             true
         } else {
             false
@@ -38,7 +38,7 @@ macro_rules! debug_once {
     });
 }
 
-/// Call `info!(...)` once per call site.
+/// Call [`info!`] once per call site.
 ///
 /// Useful for logging within systems which are called every frame.
 ///
@@ -50,7 +50,7 @@ macro_rules! info_once {
 
         static FIRST_TIME: AtomicBool = AtomicBool::new(true);
         if FIRST_TIME.swap(false, Ordering::Relaxed) {
-            info!($($arg)+);
+            $crate::info!($($arg)+);
             true
         } else {
             false
@@ -58,7 +58,7 @@ macro_rules! info_once {
     });
 }
 
-/// Call `warn!(...)` once per call site.
+/// Call [`warn!`] once per call site.
 ///
 /// Useful for logging within systems which are called every frame.
 ///
@@ -70,7 +70,7 @@ macro_rules! warn_once {
 
         static FIRST_TIME: AtomicBool = AtomicBool::new(true);
         if FIRST_TIME.swap(false, Ordering::Relaxed) {
-            warn!($($arg)+);
+            $crate::warn!($($arg)+);
             true
         } else {
             false
@@ -78,7 +78,7 @@ macro_rules! warn_once {
     });
 }
 
-/// Call `error!(...)` once per call site.
+/// Call [`error!`] once per call site.
 ///
 /// Useful for logging within systems which are called every frame.
 ///
@@ -90,7 +90,7 @@ macro_rules! error_once {
 
         static FIRST_TIME: AtomicBool = AtomicBool::new(true);
         if FIRST_TIME.swap(false, Ordering::Relaxed) {
-            error!($($arg)+);
+            $crate::error!($($arg)+);
             true
         } else {
             false

From fbca5152e4e003a6aedb0d7f9eea24ad1670b7e6 Mon Sep 17 00:00:00 2001
From: Jos Feenstra <me@josfeenstra.nl>
Date: Thu, 30 Nov 2023 09:51:49 +0100
Subject: [PATCH 06/10] extract common behavior in `once!` macro

---
 crates/bevy_log/src/once.rs | 66 ++++++++++++-------------------------
 1 file changed, 21 insertions(+), 45 deletions(-)

diff --git a/crates/bevy_log/src/once.rs b/crates/bevy_log/src/once.rs
index 3a76379baf22b..2e1ad9dc6884d 100644
--- a/crates/bevy_log/src/once.rs
+++ b/crates/bevy_log/src/once.rs
@@ -1,3 +1,19 @@
+/// Call some expression only once
+#[macro_export]
+macro_rules! once {
+    ($expression:expr) => {{
+        use ::std::sync::atomic::{AtomicBool, Ordering};
+
+        static SHOULD_FIRE: AtomicBool = AtomicBool::new(true);
+        if SHOULD_FIRE.swap(false, Ordering::Relaxed) {
+            $expression;
+            true
+        } else {
+            false
+        }
+    }};
+}
+
 /// Call [`trace!`] once per call site.
 ///
 /// Useful for logging within systems which are called every frame.
@@ -6,15 +22,7 @@
 #[macro_export]
 macro_rules! trace_once {
     ($($arg:tt)+) => ({
-        use ::std::sync::atomic::{AtomicBool, Ordering};
-
-        static FIRST_TIME: AtomicBool = AtomicBool::new(true);
-        if FIRST_TIME.swap(false, Ordering::Relaxed) {
-            $crate::trace!($($arg)+);
-            true
-        } else {
-            false
-        }
+        $crate::once!($crate::trace!($($arg)+))
     });
 }
 
@@ -26,15 +34,7 @@ macro_rules! trace_once {
 #[macro_export]
 macro_rules! debug_once {
     ($($arg:tt)+) => ({
-        use ::std::sync::atomic::{AtomicBool, Ordering};
-
-        static FIRST_TIME: AtomicBool = AtomicBool::new(true);
-        if FIRST_TIME.swap(false, Ordering::Relaxed) {
-            $crate::debug!($($arg)+);
-            true
-        } else {
-            false
-        }
+        $crate::once!($crate::debug!($($arg)+))
     });
 }
 
@@ -46,15 +46,7 @@ macro_rules! debug_once {
 #[macro_export]
 macro_rules! info_once {
     ($($arg:tt)+) => ({
-        use ::std::sync::atomic::{AtomicBool, Ordering};
-
-        static FIRST_TIME: AtomicBool = AtomicBool::new(true);
-        if FIRST_TIME.swap(false, Ordering::Relaxed) {
-            $crate::info!($($arg)+);
-            true
-        } else {
-            false
-        }
+        $crate::once!($crate::info!($($arg)+))
     });
 }
 
@@ -66,15 +58,7 @@ macro_rules! info_once {
 #[macro_export]
 macro_rules! warn_once {
     ($($arg:tt)+) => ({
-        use ::std::sync::atomic::{AtomicBool, Ordering};
-
-        static FIRST_TIME: AtomicBool = AtomicBool::new(true);
-        if FIRST_TIME.swap(false, Ordering::Relaxed) {
-            $crate::warn!($($arg)+);
-            true
-        } else {
-            false
-        }
+        $crate::once!($crate::warn!($($arg)+))
     });
 }
 
@@ -86,14 +70,6 @@ macro_rules! warn_once {
 #[macro_export]
 macro_rules! error_once {
     ($($arg:tt)+) => ({
-        use ::std::sync::atomic::{AtomicBool, Ordering};
-
-        static FIRST_TIME: AtomicBool = AtomicBool::new(true);
-        if FIRST_TIME.swap(false, Ordering::Relaxed) {
-            $crate::error!($($arg)+);
-            true
-        } else {
-            false
-        }
+        $crate::once!($crate::error!($($arg)+))
     });
 }

From da38bf91b9881d42e3ff956031b8a91e679b3232 Mon Sep 17 00:00:00 2001
From: Jos Feenstra <me@josfeenstra.nl>
Date: Thu, 30 Nov 2023 10:14:38 +0100
Subject: [PATCH 07/10] make naked `once!` macro usage possible for niche
 situations

---
 crates/bevy_log/src/once.rs | 29 +++++++++++++++--------------
 examples/app/logs.rs        | 17 ++++++++++++++++-
 2 files changed, 31 insertions(+), 15 deletions(-)

diff --git a/crates/bevy_log/src/once.rs b/crates/bevy_log/src/once.rs
index 2e1ad9dc6884d..c3e82933fda72 100644
--- a/crates/bevy_log/src/once.rs
+++ b/crates/bevy_log/src/once.rs
@@ -1,4 +1,6 @@
-/// Call some expression only once
+/// Call some expression only once per call site.
+///
+/// Returns `Some(<result-of-expression>)` on first-time call, and `None` all other times.
 #[macro_export]
 macro_rules! once {
     ($expression:expr) => {{
@@ -6,19 +8,18 @@ macro_rules! once {
 
         static SHOULD_FIRE: AtomicBool = AtomicBool::new(true);
         if SHOULD_FIRE.swap(false, Ordering::Relaxed) {
-            $expression;
-            true
+            Some($expression)
         } else {
-            false
+            None
         }
     }};
 }
 
-/// Call [`trace!`] once per call site.
+/// Call [`trace!`](crate::trace) once per call site.
 ///
 /// Useful for logging within systems which are called every frame.
 ///
-/// Returns true the first time this is called
+/// Returns `Some(())`` the first time its called
 #[macro_export]
 macro_rules! trace_once {
     ($($arg:tt)+) => ({
@@ -26,11 +27,11 @@ macro_rules! trace_once {
     });
 }
 
-/// Call [`debug!`] once per call site.
+/// Call [`debug!`](crate::debug) once per call site.
 ///
 /// Useful for logging within systems which are called every frame.
 ///
-/// Returns true the first time this is called
+/// Returns `Some(())`` the first time its called
 #[macro_export]
 macro_rules! debug_once {
     ($($arg:tt)+) => ({
@@ -38,11 +39,11 @@ macro_rules! debug_once {
     });
 }
 
-/// Call [`info!`] once per call site.
+/// Call [`info!`](crate::info) once per call site.
 ///
 /// Useful for logging within systems which are called every frame.
 ///
-/// Returns true the first time this is called
+/// Returns `Some(())`` the first time its called
 #[macro_export]
 macro_rules! info_once {
     ($($arg:tt)+) => ({
@@ -50,11 +51,11 @@ macro_rules! info_once {
     });
 }
 
-/// Call [`warn!`] once per call site.
+/// Call [`warn!`](crate::warn) once per call site.
 ///
 /// Useful for logging within systems which are called every frame.
 ///
-/// Returns true the first time this is called
+/// Returns `Some(())`` the first time its called
 #[macro_export]
 macro_rules! warn_once {
     ($($arg:tt)+) => ({
@@ -62,11 +63,11 @@ macro_rules! warn_once {
     });
 }
 
-/// Call [`error!`] once per call site.
+/// Call [`error!`](crate::error) once per call site.
 ///
 /// Useful for logging within systems which are called every frame.
 ///
-/// Returns true the first time this is called
+/// Returns `Some(())`` the first time its called
 #[macro_export]
 macro_rules! error_once {
     ($($arg:tt)+) => ({
diff --git a/examples/app/logs.rs b/examples/app/logs.rs
index 41410469ce78a..31ee2910177fb 100644
--- a/examples/app/logs.rs
+++ b/examples/app/logs.rs
@@ -1,6 +1,7 @@
 //! This example illustrates how to use logs in bevy.
 
 use bevy::prelude::*;
+use bevy_internal::log::once;
 
 fn main() {
     App::new()
@@ -46,7 +47,21 @@ fn log_once_system() {
         info_once!("logs once per call site, so this works just fine: {}", i);
     }
 
-    if info_once!("some more info") {
+    if info_once!("some more info").is_some() {
         info!("this is the first and only time 'some more info' was printed");
     }
+
+    // you can also use the 'once!' macro directly, in situations you want do do
+    // something expensive only once within the context of a continous system.
+    if let Some(result) = once!({
+        info!("doing expensive things");
+        let mut a: u64 = 0;
+        for i in 0..100000000 {
+            // ... doing expensive things
+            a += i;
+        }
+        a
+    }) {
+        info!("result of some expensive one time calculation: {}", result);
+    }
 }

From ff140abeda915ef1d1106504f35dd4955c982e4e Mon Sep 17 00:00:00 2001
From: Jos Feenstra <me@josfeenstra.nl>
Date: Thu, 30 Nov 2023 10:18:36 +0100
Subject: [PATCH 08/10] remove return types altogether, as they have become
 unnecessary

---
 crates/bevy_log/src/once.rs | 14 +-------------
 examples/app/logs.rs        | 12 +++---------
 2 files changed, 4 insertions(+), 22 deletions(-)

diff --git a/crates/bevy_log/src/once.rs b/crates/bevy_log/src/once.rs
index c3e82933fda72..7841939888d2c 100644
--- a/crates/bevy_log/src/once.rs
+++ b/crates/bevy_log/src/once.rs
@@ -8,9 +8,7 @@ macro_rules! once {
 
         static SHOULD_FIRE: AtomicBool = AtomicBool::new(true);
         if SHOULD_FIRE.swap(false, Ordering::Relaxed) {
-            Some($expression)
-        } else {
-            None
+            $expression;
         }
     }};
 }
@@ -18,8 +16,6 @@ macro_rules! once {
 /// Call [`trace!`](crate::trace) once per call site.
 ///
 /// Useful for logging within systems which are called every frame.
-///
-/// Returns `Some(())`` the first time its called
 #[macro_export]
 macro_rules! trace_once {
     ($($arg:tt)+) => ({
@@ -30,8 +26,6 @@ macro_rules! trace_once {
 /// Call [`debug!`](crate::debug) once per call site.
 ///
 /// Useful for logging within systems which are called every frame.
-///
-/// Returns `Some(())`` the first time its called
 #[macro_export]
 macro_rules! debug_once {
     ($($arg:tt)+) => ({
@@ -42,8 +36,6 @@ macro_rules! debug_once {
 /// Call [`info!`](crate::info) once per call site.
 ///
 /// Useful for logging within systems which are called every frame.
-///
-/// Returns `Some(())`` the first time its called
 #[macro_export]
 macro_rules! info_once {
     ($($arg:tt)+) => ({
@@ -54,8 +46,6 @@ macro_rules! info_once {
 /// Call [`warn!`](crate::warn) once per call site.
 ///
 /// Useful for logging within systems which are called every frame.
-///
-/// Returns `Some(())`` the first time its called
 #[macro_export]
 macro_rules! warn_once {
     ($($arg:tt)+) => ({
@@ -66,8 +56,6 @@ macro_rules! warn_once {
 /// Call [`error!`](crate::error) once per call site.
 ///
 /// Useful for logging within systems which are called every frame.
-///
-/// Returns `Some(())`` the first time its called
 #[macro_export]
 macro_rules! error_once {
     ($($arg:tt)+) => ({
diff --git a/examples/app/logs.rs b/examples/app/logs.rs
index 31ee2910177fb..01d85bbeb725b 100644
--- a/examples/app/logs.rs
+++ b/examples/app/logs.rs
@@ -47,21 +47,15 @@ fn log_once_system() {
         info_once!("logs once per call site, so this works just fine: {}", i);
     }
 
-    if info_once!("some more info").is_some() {
-        info!("this is the first and only time 'some more info' was printed");
-    }
-
     // you can also use the 'once!' macro directly, in situations you want do do
     // something expensive only once within the context of a continous system.
-    if let Some(result) = once!({
+    once!({
         info!("doing expensive things");
         let mut a: u64 = 0;
         for i in 0..100000000 {
             // ... doing expensive things
             a += i;
         }
-        a
-    }) {
-        info!("result of some expensive one time calculation: {}", result);
-    }
+        info!("result of some expensive one time calculation: {}", a);
+    });
 }

From 15591eec38d28360b5f91fabb73fc082515546d1 Mon Sep 17 00:00:00 2001
From: Jos Feenstra <me@josfeenstra.nl>
Date: Thu, 30 Nov 2023 10:22:03 +0100
Subject: [PATCH 09/10] cleanup

---
 examples/app/logs.rs | 3 +--
 1 file changed, 1 insertion(+), 2 deletions(-)

diff --git a/examples/app/logs.rs b/examples/app/logs.rs
index 01d85bbeb725b..797fd85fc121b 100644
--- a/examples/app/logs.rs
+++ b/examples/app/logs.rs
@@ -1,7 +1,7 @@
 //! This example illustrates how to use logs in bevy.
 
+use bevy::log::once;
 use bevy::prelude::*;
-use bevy_internal::log::once;
 
 fn main() {
     App::new()
@@ -53,7 +53,6 @@ fn log_once_system() {
         info!("doing expensive things");
         let mut a: u64 = 0;
         for i in 0..100000000 {
-            // ... doing expensive things
             a += i;
         }
         info!("result of some expensive one time calculation: {}", a);

From 713d2d547ea975618a47dc315dec613efe86a2cc Mon Sep 17 00:00:00 2001
From: Jos Feenstra <me@josfeenstra.nl>
Date: Thu, 30 Nov 2023 10:33:53 +0100
Subject: [PATCH 10/10] remove deprecated comment

---
 crates/bevy_log/src/once.rs | 2 --
 1 file changed, 2 deletions(-)

diff --git a/crates/bevy_log/src/once.rs b/crates/bevy_log/src/once.rs
index 7841939888d2c..9cac9f22e121b 100644
--- a/crates/bevy_log/src/once.rs
+++ b/crates/bevy_log/src/once.rs
@@ -1,6 +1,4 @@
 /// Call some expression only once per call site.
-///
-/// Returns `Some(<result-of-expression>)` on first-time call, and `None` all other times.
 #[macro_export]
 macro_rules! once {
     ($expression:expr) => {{