Improve the example in lib.rs (#957)

src/lib.rs

@@ -35,13 +35,31 @@
 //! ```no_run
 //! use winit::{
 //!     event::{Event, WindowEvent},
-//!     event_loop::ControlFlow,
+//!     event_loop::{ControlFlow, EventLoop},
+//!     window::WindowBuilder,
 //! };
-//! # use winit::event_loop::EventLoop;
-//! # let event_loop = EventLoop::new();
+//!
+//! let event_loop = EventLoop::new();
+//! let window = WindowBuilder::new().build(&event_loop).unwrap();
 //!
 //! event_loop.run(move |event, _, control_flow| {
 //!     match event {
+//!         Event::EventsCleared => {
+//!             // Application update code.
+//!     
+//!             // Queue a RedrawRequested event.
+//!             window.request_redraw();
+//!         },
+//!         Event::WindowEvent {
+//!             event: WindowEvent::RedrawRequested,
+//!             ..
+//!         } => {
+//!             // Redraw the application.
+//!             //
+//!             // It's preferrable to render in this event rather than in EventsCleared, since
+//!             // rendering in here allows the program to gracefully handle redraws requested
+//!             // by the OS.
+//!         },
 //!         Event::WindowEvent {
 //!             event: WindowEvent::CloseRequested,
 //!             ..
@@ -49,7 +67,13 @@
 //!             println!("The close button was pressed; stopping");
 //!             *control_flow = ControlFlow::Exit
 //!         },
-//!         _ => *control_flow = ControlFlow::Wait,
+//!         // ControlFlow::Poll continuously runs the event loop, even if the OS hasn't
+//!         // dispatched any events. This is ideal for games and similar applications.
+//!         _ => *control_flow = ControlFlow::Poll,
+//!         // ControlFlow::Wait pauses the event loop if no events are available to process.
+//!         // This is ideal for non-game applications that only update in response to user
+//!         // input, and uses significantly less power/CPU time than ControlFlow::Poll.
+//!         // _ => *control_flow = ControlFlow::Wait,
 //!     }
 //! });
 //! ```