Write documentation for `iced_graphics`

15 files changed, 256 insertions, 4 deletions

diff --git a/graphics/src/antialiasing.rs b/graphics/src/antialiasing.rs
index f92b3692..34d94711 100644
--- a/graphics/src/antialiasing.rs
+++ b/graphics/src/antialiasing.rs
@@ -12,6 +12,9 @@ pub enum Antialiasing {
 }
 
 impl Antialiasing {
+    /// Returns the amount of samples of the [`Antialiasing`].
+    ///
+    /// [`Antialiasing`]: enum.Antialiasing.html
     pub fn sample_count(self) -> u32 {
         match self {
             Antialiasing::MSAAx2 => 2,
diff --git a/graphics/src/backend.rs b/graphics/src/backend.rs
index ee4eca0a..83510311 100644
--- a/graphics/src/backend.rs
+++ b/graphics/src/backend.rs
@@ -1,15 +1,33 @@
+//! Write a graphics backend.
 use iced_native::image;
 use iced_native::svg;
 use iced_native::{Font, Size};
 
+/// The graphics backend of a [`Renderer`].
+///
+/// [`Renderer`]: ../struct.Renderer.html
 pub trait Backend {
+    /// Trims the measurements cache.
+    ///
+    /// This method is currently necessary to properly trim the text cache in
+    /// `iced_wgpu` and `iced_glow` because of limitations in the text rendering
+    /// pipeline. It will be removed in the future.
     fn trim_measurements(&mut self) {}
 }
 
+/// A graphics backend that supports text rendering.
 pub trait Text {
+    /// The icon font of the backend.
     const ICON_FONT: Font;
+
+    /// The `char` representing a ✔ icon in the [`ICON_FONT`].
+    ///
+    /// [`ICON_FONT`]: #associatedconst.ICON_FONt
     const CHECKMARK_ICON: char;
 
+    /// Measures the text contents with the given size and font,
+    /// returning the size of a laid out paragraph that fits in the provided
+    /// bounds.
     fn measure(
         &self,
         contents: &str,
@@ -19,10 +37,14 @@ pub trait Text {
     ) -> (f32, f32);
 }
 
+/// A graphics backend that supports image rendering.
 pub trait Image {
+    /// Returns the dimensions of the provided image.
     fn dimensions(&self, handle: &image::Handle) -> (u32, u32);
 }
 
+/// A graphics backend that supports SVG rendering.
 pub trait Svg {
+    /// Returns the viewport dimensions of the provided SVG.
     fn viewport_dimensions(&self, handle: &svg::Handle) -> (u32, u32);
 }
diff --git a/graphics/src/font.rs b/graphics/src/font.rs
index a490e609..bcc28857 100644
--- a/graphics/src/font.rs
+++ b/graphics/src/font.rs
@@ -1,22 +1,33 @@
+//! Find system fonts or use the built-in ones.
 #[cfg(feature = "font-source")]
 mod source;
 
 #[cfg(feature = "font-source")]
+#[cfg_attr(docsrs, doc(cfg(feature = "font-source")))]
 pub use source::Source;
 
 #[cfg(feature = "font-source")]
+#[cfg_attr(docsrs, doc(cfg(feature = "font-source")))]
 pub use font_kit::{
     error::SelectionError as LoadError, family_name::FamilyName as Family,
 };
 
+/// A built-in fallback font, for convenience.
 #[cfg(feature = "font-fallback")]
+#[cfg_attr(docsrs, doc(cfg(feature = "font-fallback")))]
 pub const FALLBACK: &[u8] = include_bytes!("../fonts/Lato-Regular.ttf");
 
+/// A built-in icon font, for convenience.
 #[cfg(feature = "font-icons")]
+#[cfg_attr(docsrs, doc(cfg(feature = "font-icons")))]
 pub const ICONS: iced_native::Font = iced_native::Font::External {
     name: "iced_wgpu icons",
     bytes: include_bytes!("../fonts/Icons.ttf"),
 };
 
+/// The `char` representing a ✔ icon in the built-in [`ICONS`] font.
+///
+/// [`ICONS`]: const.ICONS.html
 #[cfg(feature = "font-icons")]
+#[cfg_attr(docsrs, doc(cfg(feature = "font-icons")))]
 pub const CHECKMARK_ICON: char = '\u{F00C}';
diff --git a/graphics/src/font/source.rs b/graphics/src/font/source.rs
index 6855aa93..917291ff 100644
--- a/graphics/src/font/source.rs
+++ b/graphics/src/font/source.rs
@@ -1,16 +1,24 @@
 use crate::font::{Family, LoadError};
 
+/// A font source that can find and load system fonts.
+#[allow(missing_debug_implementations)]
 pub struct Source {
     raw: font_kit::source::SystemSource,
 }
 
 impl Source {
+    /// Creates a new [`Source`].
+    ///
+    /// [`Source`]: struct.Source.html
     pub fn new() -> Self {
         Source {
             raw: font_kit::source::SystemSource::new(),
         }
     }
 
+    /// Finds and loads a font matching the set of provided family priorities.
+    ///
+    /// [`Source`]: struct.Source.html
     pub fn load(&self, families: &[Family]) -> Result<Vec<u8>, LoadError> {
         let font = self.raw.select_best_match(
             families,
diff --git a/graphics/src/layer.rs b/graphics/src/layer.rs
index 59b792f0..6aca738e 100644
--- a/graphics/src/layer.rs
+++ b/graphics/src/layer.rs
@@ -1,3 +1,4 @@
+//! Organize rendering primitives into a flattened list of layers.
 use crate::image;
 use crate::svg;
 use crate::triangle;
@@ -6,16 +7,39 @@ use crate::{
     Vector, VerticalAlignment, Viewport,
 };
 
+/// A group of primitives that should be clipped together.
 #[derive(Debug, Clone)]
 pub struct Layer<'a> {
+    /// The clipping bounds of the [`Layer`].
+    ///
+    /// [`Layer`]: struct.Layer.html
     pub bounds: Rectangle,
+
+    /// The quads of the [`Layer`].
+    ///
+    /// [`Layer`]: struct.Layer.html
     pub quads: Vec<Quad>,
+
+    /// The triangle meshes of the [`Layer`].
+    ///
+    /// [`Layer`]: struct.Layer.html
     pub meshes: Vec<Mesh<'a>>,
+
+    /// The text of the [`Layer`].
+    ///
+    /// [`Layer`]: struct.Layer.html
     pub text: Vec<Text<'a>>,
+
+    /// The images of the [`Layer`].
+    ///
+    /// [`Layer`]: struct.Layer.html
     pub images: Vec<Image>,
 }
 
 impl<'a> Layer<'a> {
+    /// Creates a new [`Layer`] with the given clipping bounds.
+    ///
+    /// [`Layer`]: struct.Layer.html
     pub fn new(bounds: Rectangle) -> Self {
         Self {
             bounds,
@@ -26,6 +50,11 @@ impl<'a> Layer<'a> {
         }
     }
 
+    /// Creates a new [`Layer`] for the provided overlay text.
+    ///
+    /// This can be useful for displaying debug information.
+    ///
+    /// [`Layer`]: struct.Layer.html
     pub fn overlay(lines: &'a [impl AsRef<str>], viewport: &Viewport) -> Self {
         let mut overlay =
             Layer::new(Rectangle::with_size(viewport.logical_size()));
@@ -56,6 +85,10 @@ impl<'a> Layer<'a> {
         overlay
     }
 
+    /// Distributes the given [`Primitive`] and generates a list of layers based
+    /// on its contents.
+    ///
+    /// [`Primitive`]: ../enum.Primitive.html
     pub fn generate(
         primitive: &'a Primitive,
         viewport: &Viewport,
@@ -119,7 +152,7 @@ impl<'a> Layer<'a> {
                         bounds.x + translation.x,
                         bounds.y + translation.y,
                     ],
-                    scale: [bounds.width, bounds.height],
+                    size: [bounds.width, bounds.height],
                     color: match background {
                         Background::Color(color) => color.into_linear(),
                     },
@@ -203,46 +236,124 @@ impl<'a> Layer<'a> {
     }
 }
 
+/// A colored rectangle with a border.
+///
+/// This type can be directly uploaded to GPU memory.
 #[derive(Debug, Clone, Copy)]
 #[repr(C)]
 pub struct Quad {
+    /// The position of the [`Quad`].
+    ///
+    /// [`Quad`]: struct.Quad.html
     pub position: [f32; 2],
-    pub scale: [f32; 2],
+
+    /// The size of the [`Quad`].
+    ///
+    /// [`Quad`]: struct.Quad.html
+    pub size: [f32; 2],
+
+    /// The color of the [`Quad`], in __linear RGB__.
+    ///
+    /// [`Quad`]: struct.Quad.html
     pub color: [f32; 4],
+
+    /// The border color of the [`Quad`], in __linear RGB__.
+    ///
+    /// [`Quad`]: struct.Quad.html
     pub border_color: [f32; 4],
+
+    /// The border radius of the [`Quad`].
+    ///
+    /// [`Quad`]: struct.Quad.html
     pub border_radius: f32,
+
+    /// The border width of the [`Quad`].
+    ///
+    /// [`Quad`]: struct.Quad.html
     pub border_width: f32,
 }
 
+/// A mesh of triangles.
 #[derive(Debug, Clone, Copy)]
 pub struct Mesh<'a> {
+    /// The origin of the vertices of the [`Mesh`].
+    ///
+    /// [`Mesh`]: struct.Mesh.html
     pub origin: Point,
+
+    /// The vertex and index buffers of the [`Mesh`].
+    ///
+    /// [`Mesh`]: struct.Mesh.html
     pub buffers: &'a triangle::Mesh2D,
+
+    /// The clipping bounds of the [`Mesh`].
+    ///
+    /// [`Mesh`]: struct.Mesh.html
     pub clip_bounds: Rectangle<f32>,
 }
 
+/// A paragraph of text.
 #[derive(Debug, Clone, Copy)]
 pub struct Text<'a> {
+    /// The content of the [`Text`].
+    ///
+    /// [`Text`]: struct.Text.html
     pub content: &'a str,
+
+    /// The layout bounds of the [`Text`].
+    ///
+    /// [`Text`]: struct.Text.html
     pub bounds: Rectangle,
+
+    /// The color of the [`Text`], in __linear RGB_.
+    ///
+    /// [`Text`]: struct.Text.html
     pub color: [f32; 4],
+
+    /// The size of the [`Text`].
+    ///
+    /// [`Text`]: struct.Text.html
     pub size: f32,
+
+    /// The font of the [`Text`].
+    ///
+    /// [`Text`]: struct.Text.html
     pub font: Font,
+
+    /// The horizontal alignment of the [`Text`].
+    ///
+    /// [`Text`]: struct.Text.html
     pub horizontal_alignment: HorizontalAlignment,
+
+    /// The vertical alignment of the [`Text`].
+    ///
+    /// [`Text`]: struct.Text.html
     pub vertical_alignment: VerticalAlignment,
 }
 
+/// A raster or vector image.
 #[derive(Debug, Clone)]
 pub enum Image {
+    /// A raster image.
     Raster {
+        /// The handle of a raster image.
         handle: image::Handle,
+
+        /// The bounds of the image.
         bounds: Rectangle,
     },
+    /// A vector image.
     Vector {
+        /// The handle of a vector image.
         handle: svg::Handle,
+
+        /// The bounds of the image.
         bounds: Rectangle,
     },
 }
 
+#[allow(unsafe_code)]
 unsafe impl bytemuck::Zeroable for Quad {}
+
+#[allow(unsafe_code)]
 unsafe impl bytemuck::Pod for Quad {}
diff --git a/graphics/src/lib.rs b/graphics/src/lib.rs
index 2de9d21c..b6dda132 100644
--- a/graphics/src/lib.rs
+++ b/graphics/src/lib.rs
@@ -1,3 +1,13 @@
+//! A bunch of backend-agnostic types that can be leveraged to build a renderer
+//! for [`iced`].
+//!
+//! [`iced`]: https://github.com/hecrj/iced
+#![deny(missing_docs)]
+#![deny(missing_debug_implementations)]
+#![deny(unused_results)]
+#![deny(unsafe_code)]
+#![forbid(rust_2018_idioms)]
+#![cfg_attr(docsrs, feature(doc_cfg))]
 mod antialiasing;
 mod defaults;
 mod primitive;
diff --git a/graphics/src/renderer.rs b/graphics/src/renderer.rs
index f16e04b1..c9360f3a 100644
--- a/graphics/src/renderer.rs
+++ b/graphics/src/renderer.rs
@@ -3,19 +3,33 @@ use iced_native::layout::{self, Layout};
 use iced_native::mouse;
 use iced_native::{Background, Color, Element, Point, Widget};
 
-pub struct Renderer<B> {
+/// A backend-agnostic renderer that supports all the built-in widgets.
+#[derive(Debug)]
+pub struct Renderer<B: Backend> {
     backend: B,
 }
 
-impl<B> Renderer<B> {
+impl<B: Backend> Renderer<B> {
+    /// Creates a new [`Renderer`] from the given [`Backend`].
+    ///
+    /// [`Renderer`]: struct.Renderer.html
+    /// [`Backend`]: backend/trait.Backend.html
     pub fn new(backend: B) -> Self {
         Self { backend }
     }
 
+    /// Returns a reference to the [`Backend`] of the [`Renderer`].
+    ///
+    /// [`Renderer`]: struct.Renderer.html
+    /// [`Backend`]: backend/trait.Backend.html
     pub fn backend(&self) -> &B {
         &self.backend
     }
 
+    /// Returns a mutable reference to the [`Backend`] of the [`Renderer`].
+    ///
+    /// [`Renderer`]: struct.Renderer.html
+    /// [`Backend`]: backend/trait.Backend.html
     pub fn backend_mut(&mut self) -> &mut B {
         &mut self.backend
     }
diff --git a/graphics/src/triangle.rs b/graphics/src/triangle.rs
index 474f69b8..ce879ffc 100644
--- a/graphics/src/triangle.rs
+++ b/graphics/src/triangle.rs
@@ -1,3 +1,5 @@
+//! Draw geometry using meshes of triangles.
+
 /// A set of [`Vertex2D`] and indices representing a list of triangles.
 ///
 /// [`Vertex2D`]: struct.Vertex2D.html
@@ -23,5 +25,8 @@ pub struct Vertex2D {
     pub color: [f32; 4],
 }
 
+#[allow(unsafe_code)]
 unsafe impl bytemuck::Zeroable for Vertex2D {}
+
+#[allow(unsafe_code)]
 unsafe impl bytemuck::Pod for Vertex2D {}
diff --git a/graphics/src/viewport.rs b/graphics/src/viewport.rs
index 745ef339..66122e6d 100644
--- a/graphics/src/viewport.rs
+++ b/graphics/src/viewport.rs
@@ -26,22 +26,44 @@ impl Viewport {
         }
     }
 
+    /// Returns the physical size of the [`Viewport`].
+    ///
+    /// [`Viewport`]: struct.Viewport.html
     pub fn physical_size(&self) -> Size<u32> {
         self.physical_size
     }
 
+    /// Returns the physical width of the [`Viewport`].
+    ///
+    /// [`Viewport`]: struct.Viewport.html
+    pub fn physical_width(&self) -> u32 {
+        self.physical_size.height
+    }
+
+    /// Returns the physical height of the [`Viewport`].
+    ///
+    /// [`Viewport`]: struct.Viewport.html
     pub fn physical_height(&self) -> u32 {
         self.physical_size.height
     }
 
+    /// Returns the logical size of the [`Viewport`].
+    ///
+    /// [`Viewport`]: struct.Viewport.html
     pub fn logical_size(&self) -> Size<f32> {
         self.logical_size
     }
 
+    /// Returns the scale factor of the [`Viewport`].
+    ///
+    /// [`Viewport`]: struct.Viewport.html
     pub fn scale_factor(&self) -> f64 {
         self.scale_factor
     }
 
+    /// Returns the projection transformation of the [`Viewport`].
+    ///
+    /// [`Viewport`]: struct.Viewport.html
     pub fn projection(&self) -> Transformation {
         self.projection
     }
diff --git a/graphics/src/widget/column.rs b/graphics/src/widget/column.rs
index 9183d2ee..6c7235c7 100644
--- a/graphics/src/widget/column.rs
+++ b/graphics/src/widget/column.rs
@@ -3,6 +3,7 @@ use iced_native::column;
 use iced_native::mouse;
 use iced_native::{Element, Layout, Point};
 
+/// A container that distributes its contents vertically.
 pub type Column<'a, Message, Backend> =
     iced_native::Column<'a, Message, Renderer<Backend>>;
 
diff --git a/graphics/src/widget/image.rs b/graphics/src/widget/image.rs
index ea49febe..30f446e8 100644
--- a/graphics/src/widget/image.rs
+++ b/graphics/src/widget/image.rs
@@ -1,3 +1,4 @@
+//! Display images in your user interface.
 use crate::backend::{self, Backend};
 use crate::{Primitive, Renderer};
 use iced_native::image;
diff --git a/graphics/src/widget/row.rs b/graphics/src/widget/row.rs
index 9865d0de..4c1dbadc 100644
--- a/graphics/src/widget/row.rs
+++ b/graphics/src/widget/row.rs
@@ -3,6 +3,7 @@ use iced_native::mouse;
 use iced_native::row;
 use iced_native::{Element, Layout, Point};
 
+/// A container that distributes its contents horizontally.
 pub type Row<'a, Message, Backend> =
     iced_native::Row<'a, Message, Renderer<Backend>>;
 
diff --git a/graphics/src/widget/svg.rs b/graphics/src/widget/svg.rs
index 8c681478..8b5ed66a 100644
--- a/graphics/src/widget/svg.rs
+++ b/graphics/src/widget/svg.rs
@@ -1,3 +1,4 @@
+//! Display vector graphics in your application.
 use crate::backend::{self, Backend};
 use crate::{Primitive, Renderer};
 use iced_native::{mouse, svg, Layout};
diff --git a/graphics/src/window.rs b/graphics/src/window.rs
index 380efb8c..3e74db5f 100644
--- a/graphics/src/window.rs
+++ b/graphics/src/window.rs
@@ -1,3 +1,4 @@
+//! Draw graphics to window surfaces.
 mod compositor;
 
 #[cfg(feature = "opengl")]
diff --git a/graphics/src/window/gl_compositor.rs b/graphics/src/window/gl_compositor.rs
index aea898e3..542213b5 100644
--- a/graphics/src/window/gl_compositor.rs
+++ b/graphics/src/window/gl_compositor.rs
@@ -3,19 +3,60 @@ use iced_native::mouse;
 
 use core::ffi::c_void;
 
+/// A basic OpenGL compositor.
+///
+/// A compositor is responsible for initializing a renderer and managing window
+/// surfaces.
+///
+/// For now, this compositor only deals with a single global surface
+/// for drawing. However, the trait will most likely change in the near future
+/// to handle multiple surfaces at once.
+///
+/// If you implement an OpenGL renderer, you can implement this trait to ease
+/// integration with existing windowing shells, like `iced_glutin`.
 pub trait GLCompositor: Sized {
+    /// The renderer of the [`Compositor`].
+    ///
+    /// This should point to your renderer type, which could be a type alias
+    /// of the [`Renderer`] provided in this crate with with a specific
+    /// [`Backend`].
+    ///
+    /// [`Compositor`]: trait.Compositor.html
+    /// [`Renderer`]: ../struct.Renderer.html
+    /// [`Backend`]: ../backend/trait.Backend.html
     type Renderer: iced_native::Renderer;
+
+    /// The settings of the [`Compositor`].
+    ///
+    /// It's up to you to decide the configuration supported by your renderer!
     type Settings: Default;
 
+    /// Creates a new [`Compositor`] and [`Renderer`] with the given
+    /// [`Settings`] and an OpenGL address loader function.
+    ///
+    /// [`Compositor`]: trait.Compositor.html
+    /// [`Renderer`]: #associatedtype.Renderer
+    /// [`Backend`]: ../backend/trait.Backend.html
+    #[allow(unsafe_code)]
     unsafe fn new(
         settings: Self::Settings,
         loader_function: impl FnMut(&str) -> *const c_void,
     ) -> (Self, Self::Renderer);
 
+    /// Returns the amount of samples that should be used when configuring
+    /// an OpenGL context for this [`Compositor`].
+    ///
+    /// [`Compositor`]: trait.Compositor.html
     fn sample_count(settings: &Self::Settings) -> u32;
 
+    /// Resizes the viewport of the [`Compositor`].
+    ///
+    /// [`Compositor`]: trait.Compositor.html
     fn resize_viewport(&mut self, physical_size: Size<u32>);
 
+    /// Draws the provided output with the given [`Renderer`].
+    ///
+    /// [`Compositor`]: trait.Compositor.html
     fn draw<T: AsRef<str>>(
         &mut self,
         renderer: &mut Self::Renderer,