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);
 }