message: Add example for `Canvas` widget
diff: @@ -33,11 +33,48 @@ pub use text::Text;
  /// A widget capable of drawing 2D graphics.
  ///
  /// A [`Canvas`] may contain multiple layers. A [`Layer`] is drawn using the
  -/// painter's algorithm. In other words, layers will be drawn on top of each in
  -/// the same order they are pushed into the [`Canvas`].
  +/// painter's algorithm. In other words, layers will be drawn on top of each
  +/// other in the same order they are pushed into the [`Canvas`].
  ///
  /// [`Canvas`]: struct.Canvas.html
  /// [`Layer`]: layer/trait.Layer.html
  +///
  +/// # Example
  +/// Let's see how we can draw a circle:
  +///
  +/// ```
  +/// # mod iced {
  +/// # pub use iced_wgpu::canvas;
  +/// # pub use iced_native::Color;
  +/// # }
  +/// use iced::canvas::{self, layer, Canvas, Drawable, Fill, Frame, Path};
  +/// use iced::Color;
  +///
  +/// // First, we define the data we need for drawing
  +/// #[derive(Debug)]
  +/// struct Circle {
  +/// radius: f32,
  +/// }
  +///
  +/// // Then, we implement the `Drawable` trait
  +/// impl Drawable for Circle {
  +/// fn draw(&self, frame: &mut Frame) {
  +/// // We create a `Path` representing a simple circle
  +/// let circle = Path::new(|p| p.circle(frame.center(), self.radius));
  +///
  +/// // And fill it with some color
  +/// frame.fill(&circle, Fill::Color(Color::BLACK));
  +/// }
  +/// }
  +///
  +/// // We can use a `Cache` to avoid unnecessary re-tessellation
  +/// let cache: layer::Cache<Circle> = layer::Cache::new();
  +///
  +/// // Finally, we simply provide the data to our `Cache` and push the resulting
  +/// // layer into a `Canvas`
  +/// let canvas = Canvas::new()
  +/// .push(cache.with(&Circle { radius: 50.0 }));
  +/// ```
  #[derive(Debug)]
  pub struct Canvas<'a> {
  width: Length,
  