Clarify when RedrawRequested is useful (#1529)

Co-Authored-By: Osspial <osspial@gmail.com>

src/event.rs

@@ -81,10 +81,11 @@ pub enum Event<'a, T: 'static> {
     ///
     /// This event is useful as a place to put your code that should be run after all
     /// state-changing events have been handled and you want to do stuff (updating state, performing
-    /// calculations, etc) that happens as the "main body" of your event loop. If your program draws
-    /// graphics, it's usually better to do it in response to
+    /// calculations, etc) that happens as the "main body" of your event loop. If your program only draws
+    /// graphics when something changes, it's usually better to do it in response to
     /// [`Event::RedrawRequested`](crate::event::Event::RedrawRequested), which gets emitted
-    /// immediately after this event.
+    /// immediately after this event. Programs that draw graphics continuously, like most games,
+    /// can render here unconditionally for simplicity.
     MainEventsCleared,
 
     /// Emitted after `MainEventsCleared` when a window should be redrawn.
@@ -97,6 +98,9 @@ pub enum Event<'a, T: 'static> {
     ///
     /// During each iteration of the event loop, Winit will aggregate duplicate redraw requests
     /// into a single event, to help avoid duplicating rendering work.
+    ///
+    /// Mainly of interest to applications with mostly-static graphics that avoid redrawing unless
+    /// something changes, like most non-game GUIs.
     RedrawRequested(WindowId),
 
     /// Emitted after all `RedrawRequested` events have been processed and control flow is about to

src/lib.rs

@@ -73,14 +73,18 @@
 //!             // Application update code.
 //!
 //!             // Queue a RedrawRequested event.
+//!             //
+//!             // You only need to call this if you've determined that you need to redraw, in
+//!             // applications which do not always need to. Applications that redraw continuously
+//!             // can just render here instead.
 //!             window.request_redraw();
 //!         },
 //!         Event::RedrawRequested(_) => {
 //!             // Redraw the application.
 //!             //
-//!             // It's preferrable to render in this event rather than in MainEventsCleared, since
-//!             // rendering in here allows the program to gracefully handle redraws requested
-//!             // by the OS.
+//!             // It's preferable for applications that do not render continuously to render in
+//!             // this event rather than in MainEventsCleared, since rendering in here allows
+//!             // the program to gracefully handle redraws requested by the OS.
 //!         },
 //!         _ => ()
 //!     }