Improve documentation

README.md

@@ -4,7 +4,7 @@ A generic [`piet`] rendering context for all windowing and graphics backends.
 
 Windowing frameworks like [`winit`] do not provide a way to draw into them by default. This decision is intentional; it allows the user to choose which graphics backend that they'd like to use, and also makes maintaining the windowing code much simpler. For games (what [`winit`] was originally designed for), usually a 3D rendering context like [`wgpu`] or [`glow`] would be used in this case. However, GUI applications will need a 2D vector graphics context.
 
-[`piet`] is a 2D graphics abstraction that can be used with many different graphics backends. However, [`piet`]'s default implementation, [`piet-common`], is difficult to integrate with windowing systems. [`theo`] aims to bridge this gap by providing a generic [`piet`] rendering context that easily integrates with windowing systems.
+[`piet`] is a 2D graphics abstraction that can be used with many different graphics backends. However, [`piet`]'s default implementation, [`piet-common`], is difficult to integrate with windowing systems other than [`druid-shell`], which doesn't support many operations that other windowing systems support. [`theo`] aims to bridge this gap by providing a generic [`piet`] rendering context that easily integrates with windowing systems.
 
 Rather than going through drawing APIs like [`cairo`] and DirectX, `theo` directly uses GPU APIs in order to render to the window. This allows for better performance and greater flexibility, and also ensures that much of the rendering logic is safe. This also reduces the number of dynamic dependencies that your final program needs to rely on.
 
@@ -19,6 +19,7 @@ use piet::{RenderContext as _, kurbo::Circle};
 use theo::{Display, Surface, RenderContext};
 
 // Create a display using a display handle from your windowing framework.
+// `my_display` is used as a stand-in for the root of your display system.
 // It must implement `raw_window_handle::HasRawDisplayHandle`.
 let mut display = unsafe {
     Display::builder()
@@ -27,6 +28,7 @@ let mut display = unsafe {
 };
 
 // Create a surface using a window handle from your windowing framework.
+// `window` is used as a stand-in for a window in your display system.
 // It must implement `raw_window_handle::HasRawWindowHandle`.
 let surface_future = unsafe {
     display.make_surface(
@@ -40,7 +42,7 @@ let surface_future = unsafe {
 let mut surface = surface_future.await.expect("failed to create surface");
 
 // Set up drawing logic.
-surface.on_draw(move || {
+surface.on_draw(move || async move {
     // Create the render context.
     let mut ctx = RenderContext::new(
         &mut display,
@@ -58,6 +60,10 @@ surface.on_draw(move || {
 
     // Finish drawing.
     ctx.finish().expect("failed to finish drawing");
+
+    // If you don't have any other windows to draw, make sure the windows are
+    // presented.
+    display.present().await.expect("failed to present");
 });
 ```
 
@@ -122,7 +128,6 @@ either:
 * GNU Lesser General Public License as published by the Free Software Foundation, either
 version 3 of the License, or (at your option) any later version.
 * Mozilla Public License as published by the Mozilla Foundation, version 2.
-* The Patron License (https://github.com/notgull/theo/blob/main/LICENSE-PATRON.md) for sponsors and contributors, who can ignore the copyleft provisions of the above licenses or this project.
 
 `theo` is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY;
 without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.

src/lib.rs

@@ -88,7 +88,7 @@
 //! let mut surface = surface_future.await.expect("failed to create surface");
 //!
 //! // Set up drawing logic.
-//! window.on_draw(|| {
+//! window.on_draw(move || async move {
 //!     // Create the render context.
 //!     let mut ctx = RenderContext::new(
 //!         &mut display,
@@ -106,6 +106,9 @@
 //!
 //!     // Finish drawing.
 //!     ctx.finish().expect("failed to finish drawing");
+//!
+//!     // Present the display.
+//!     display.present().await.expect("failed to present display");
 //! });
 //! # });
 //! ```
@@ -1035,7 +1038,13 @@ macro_rules! make_dispatch {
 
             /// Push the queue and present to all known surfaces.
             ///
-            /// This is necessary to call after all windows have been drawn to.
+            /// This is necessary to call after all windows have been drawn to. It should be called
+            /// once all windows that need to be drawn to have already been drawn to.
+            ///
+            /// # Asynchronous
+            ///
+            /// For most backends, this is a no-op. For [`wgpu`], it submits the queue and then
+            /// waits for all of the queues to finish submitting.
             pub async fn present(&mut self) {
                 match &mut *self.dispatch {
                     $(