Added some "how" and "why" docs to event handling. (#1032)

* Added some "how" and "why" docs to event handling.

Basically I had these questions when I started exploring the new
event API's, and as I figured out the answers I put down more info
about how everything works.  This is not final, and suggestions
are welcome -- the code example in the `event` module docs is
particularly dubious, but it's how I'm used to thinking abou things
so it only made sense to me once I wrote that.

Note that my bias is towards using winit for writing games, so that's
the sort of things I was interested in.  This may not be valid for
more general use cases.

* cargo fmt

* Fix minor typos

* Revise event documentation

* Update lib.rs docs

* Update root docs

Co-authored-by: Osspial <osspial@gmail.com>

src/event.rs

@@ -3,6 +3,35 @@
 //! These are sent to the closure given to [`EventLoop::run(...)`][event_loop_run], where they get
 //! processed and used to modify the program state. For more details, see the root-level documentation.
 //!
+//! Some of these events represent different "parts" of a traditional event-handling loop. You could
+//! approximate the basic ordering loop of [`EventLoop::run(...)`][event_loop_run] like this:
+//!
+//! ```rust,ignore
+//! let mut control_flow = ControlFlow::Poll;
+//! let mut start_cause = StartCause::Init;
+//!
+//! while control_flow != ControlFlow::Exit {
+//!     event_handler(NewEvents(start_cause), ..., &mut control_flow);
+//!
+//!     for e in (window events, user events, device events) {
+//!         event_handler(e, ..., &mut control_flow);
+//!     }
+//!     event_handler(MainEventsCleared, ..., &mut control_flow);
+//!
+//!     for w in (redraw windows) {
+//!         event_handler(RedrawRequested(w), ..., &mut control_flow);
+//!     }
+//!     event_handler(RedrawEventsCleared, ..., &mut control_flow);
+//!
+//!     start_cause = wait_if_necessary(control_flow);
+//! }
+//!
+//! event_handler(LoopDestroyed, ..., &mut control_flow);
+//! ```
+//!
+//! This leaves out timing details like `ControlFlow::WaitUntil` but hopefully
+//! describes what happens in what order.
+//!
 //! [event_loop_run]: crate::event_loop::EventLoop::run
 use instant::Instant;
 use std::path::PathBuf;
@@ -14,48 +43,75 @@ use crate::{
 };
 
 /// Describes a generic event.
+///
+/// See the module-level docs for more information on the event loop manages each event.
 #[derive(Clone, Debug, PartialEq)]
 pub enum Event<T> {
+    /// Emitted when new events arrive from the OS to be processed.
+    ///
+    /// This event type is useful as a place to put code that should be done before you start
+    /// processing events, such as updating frame timing information for benchmarking or checking
+    /// the [`StartCause`][crate::event::StartCause] to see if a timer set by
+    /// [`ControlFlow::WaitUntil`](crate::event_loop::ControlFlow::WaitUntil) has elapsed.
+    NewEvents(StartCause),
+
     /// Emitted when the OS sends an event to a winit window.
     WindowEvent {
         window_id: WindowId,
         event: WindowEvent,
     },
+
     /// Emitted when the OS sends an event to a device.
     DeviceEvent {
         device_id: DeviceId,
         event: DeviceEvent,
     },
+
     /// Emitted when an event is sent from [`EventLoopProxy::send_event`](crate::event_loop::EventLoopProxy::send_event)
     UserEvent(T),
-    /// Emitted when new events arrive from the OS to be processed.
-    NewEvents(StartCause),
-    /// Emitted when all events (except for `RedrawRequested`) have been reported.
-    ///
-    /// This event is followed by zero or more instances of `RedrawRequested`
-    /// and, finally, `RedrawEventsCleared`.
-    MainEventsCleared,
-
-    /// The OS or application has requested that a window be redrawn.
-    ///
-    /// Emitted only after `MainEventsCleared`.
-    RedrawRequested(WindowId),
-
-    /// Emitted after any `RedrawRequested` events.
-    ///
-    /// If there are no `RedrawRequested` events, it is reported immediately after
-    /// `MainEventsCleared`.
-    RedrawEventsCleared,
-
-    /// Emitted when the event loop is being shut down. This is irreversable - if this event is
-    /// emitted, it is guaranteed to be the last event emitted.
-    LoopDestroyed,
 
     /// Emitted when the application has been suspended.
     Suspended,
 
     /// Emitted when the application has been resumed.
     Resumed,
+
+    /// Emitted when all of the event loop's input events have been processed and redraw processing
+    /// is about to begin.
+    ///
+    /// 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
+    /// [`Event::RedrawRequested`](crate::event::Event::RedrawRequested), which gets emitted
+    /// immediately after this event.
+    MainEventsCleared,
+
+    /// Emitted after `MainEventsCleared` when a window should be redrawn.
+    ///
+    /// This gets triggered in two scenarios:
+    /// - The OS has performed an operation that's invalidated the window's contents (such as
+    ///   resizing the window).
+    /// - The application has explicitly requested a redraw via
+    ///   [`Window::request_redraw`](crate::window::Window::request_redraw).
+    ///
+    /// During each iteration of the event loop, Winit will aggregate duplicate redraw requests
+    /// into a single event, to help avoid duplicating rendering work.
+    RedrawRequested(WindowId),
+
+    /// Emitted after all `RedrawRequested` events have been processed and control flow is about to
+    /// be taken away from the program. If there are no `RedrawRequested` events, it is emitted
+    /// immediately after `MainEventsCleared`.
+    ///
+    /// This event is useful for doing any cleanup or bookkeeping work after all the rendering
+    /// tasks have been completed.
+    RedrawEventsCleared,
+
+    /// Emitted when the event loop is being shut down.
+    ///
+    /// This is irreversable - if this event is emitted, it is guaranteed to be the last event that
+    /// gets emitted. You generally want to treat this as an "do on quit" event.
+    LoopDestroyed,
 }
 
 impl<T> Event<T> {