From b88bec9ca338e9d9f4bf269d52866b5040e3ac78 Mon Sep 17 00:00:00 2001
From: Emil Ernerfeldt <emil.ernerfeldt@gmail.com>
Date: Tue, 28 Dec 2021 10:05:10 +0100
Subject: [PATCH] Document that `CtxRef` is generational and shouldn't be
 stored

Related to https://github.com/emilk/egui/issues/1005
---
 egui/src/context.rs | 17 ++++++++++-------
 1 file changed, 10 insertions(+), 7 deletions(-)

diff --git a/egui/src/context.rs b/egui/src/context.rs
index 83032b2d..c506b3b4 100644
--- a/egui/src/context.rs
+++ b/egui/src/context.rs
@@ -26,6 +26,9 @@ use epaint::{stats::*, text::Fonts, *};
 ///
 /// [`CtxRef`] is cheap to clone, and any clones refers to the same mutable data.
 ///
+/// A [`CtxRef`] is only valid for the duration of a frame, and so you should not store a [`CtxRef`] between frames.
+/// A new [`CtxRef`] is created each frame by calling [`Self::run`].
+///
 /// # Example:
 ///
 /// ``` no_run
@@ -49,7 +52,6 @@ use epaint::{stats::*, text::Fonts, *};
 ///     paint(clipped_meshes);
 /// }
 /// ```
-///
 #[derive(Clone)]
 pub struct CtxRef(std::sync::Arc<Context>);
 
@@ -325,16 +327,17 @@ impl CtxRef {
 
 // ----------------------------------------------------------------------------
 
-/// This is the first thing you need when working with egui. Create using [`CtxRef`].
+/// Your handle to egui.
 ///
-/// Contains the [`InputState`], [`Memory`], [`Output`], and more.
+/// This is the first thing you need when working with egui.
+/// Use [`CtxRef`] to create and refer to a [`Context`].
 ///
-/// Your handle to Egui.
+/// Contains the [`InputState`], [`Memory`], [`Output`], and more.///
 ///
-/// Almost all methods are marked `&self`, `Context` has interior mutability (protected by mutexes).
+/// Almost all methods are marked `&self`, [`Context`] has interior mutability (protected by mutexes).
 /// Multi-threaded access to a [`Context`] is behind the feature flag `multi_threaded`.
 /// Normally you'd always do all ui work on one thread, or perhaps use multiple contexts,
-/// but if you really want to access the same Context from multiple threads, it *SHOULD* be fine,
+/// but if you really want to access the same [`Context`] from multiple threads, it *SHOULD* be fine,
 /// but you are likely the first person to try it.
 #[derive(Default)]
 pub struct Context {
@@ -343,7 +346,7 @@ pub struct Context {
     // This means everything else needs to be behind an Arc.
     // We can probably come up with a nicer design.
     //
-    /// None until first call to `begin_frame`.
+    /// `None` until the start of the first frame.
     fonts: Option<Arc<Fonts>>,
     memory: Arc<Mutex<Memory>>,
     animation_manager: Arc<Mutex<AnimationManager>>,