From 6c2dade6055a98c740c8201d4b94bc6b21a4aa1a Mon Sep 17 00:00:00 2001
From: KodrAus <kodraus@hey.com>
Date: Wed, 20 Mar 2024 08:11:55 +1000
Subject: [PATCH] add some clarifications to the library docs

---
 src/lib.rs | 7 +++++++
 1 file changed, 7 insertions(+)

diff --git a/src/lib.rs b/src/lib.rs
index 6b5eafbf4..69c627a8e 100644
--- a/src/lib.rs
+++ b/src/lib.rs
@@ -40,6 +40,8 @@
 //! [`debug!`]: ./macro.debug.html
 //! [`trace!`]: ./macro.trace.html
 //! [`println!`]: https://doc.rust-lang.org/stable/std/macro.println.html
+//! 
+//! Avoid writing expressions with side-effects in log statements. They may not be evaluated.
 //!
 //! ## In libraries
 //!
@@ -1149,6 +1151,11 @@ pub trait Log: Sync + Send {
     fn log(&self, record: &Record);
 
     /// Flushes any buffered records.
+    /// 
+    /// # For implementors
+    /// 
+    /// This method isn't called automatically by the `log!` macros.
+    /// It can be called manually on shut-down to ensure any in-flight records are flushed.
     fn flush(&self);
 }