fix: correct safety docs of expectation returning methodsHEADmaster

1 files changed, 67 insertions, 2 deletions

diff --git a/macros/src/expectation.rs b/macros/src/expectation.rs
index d724655..c5cd758 100644
--- a/macros/src/expectation.rs
+++ b/macros/src/expectation.rs
@@ -443,8 +443,73 @@ impl ToTokens for Expectation
                 /// this expectation.
                 ///
                 /// # Safety
-                /// The caller must ensure that no argument or return type is outlived. They must
-                /// be treated as if they are bound to 'static.
+                /// The caller must ensure that no argument or return type is used in a
+                /// way that exceeds its actual lifetime.
+                ///
+                /// This example is **OK**:
+                /// ```
+                /// use ridicule::automock;
+                ///
+                /// #[automock]
+                /// trait Foo
+                /// {
+                ///     fn do_stuff<Something>(&self, something: Something);
+                /// }
+                ///
+                /// # fn main() {
+                /// let mut mock_foo = MockFoo::new();
+                ///
+                /// unsafe {
+                ///     mock_foo.expect_do_stuff::<u32>().returning(|_, something| {
+                ///         println!("Doing stuff with {something}");
+                ///     });
+                /// }
+                ///
+                /// mock_foo.do_stuff(1234u32);
+                /// # }
+                /// ```
+                ///
+                /// This example is **NOT OK**:
+                /// ```no_run
+                /// use std::slice::Chunks;
+                /// use std::sync::Mutex;
+                ///
+                /// use ridicule::automock;
+                ///
+                /// static cool_chunks: Mutex<Option<Chunks<i64>>> = Mutex::new(None);
+                ///
+                /// #[automock]
+                /// trait Foo
+                /// {
+                ///     fn do_stuff<Something>(&self, something: Something);
+                /// }
+                ///
+                /// # fn main() {
+                /// let mut mock_foo = MockFoo::new();
+                ///
+                /// unsafe {
+                ///     mock_foo.expect_do_stuff::<Chunks<i64>>().returning(|_, chunks| {
+                ///         // NEVER EVER DO THIS
+                ///         *cool_chunks.lock().unwrap() = Some(chunks);
+                ///     });
+                /// }
+                ///
+                /// {
+                ///     let items: Vec<i64> = Vec::from([9876, 567, 13579, -234, 890, -765]);
+                ///
+                ///     mock_foo.do_stuff(items.chunks(2));
+                ///
+                ///     // items go out of scope here
+                /// }
+                ///
+                /// let cool_chunks_lock = cool_chunks.lock().unwrap();
+                ///
+                /// // Undefined behavior here
+                /// let mut cool_chunks_cloned = cool_chunks_lock.clone().unwrap();
+                ///
+                /// let garbage = cool_chunks_cloned.next();
+                /// # }
+                /// ```
                 #[allow(unused)]
                 pub unsafe fn returning(
                     &mut self,