Write renderer docs and fix broken links

examples/ggez/renderer.rs

@@ -4,7 +4,7 @@ mod radio;
 mod slider;
 mod text;
 
-use ggez::graphics::{self, spritebatch::SpriteBatch, Color, Image};
+use ggez::graphics::{self, spritebatch::SpriteBatch, Image};
 use ggez::Context;
 
 pub struct Renderer<'a> {
@@ -39,9 +39,3 @@ impl Renderer<'_> {
         .expect("Draw text");
     }
 }
-
-impl iced::Renderer for Renderer<'_> {
-    type Color = Color;
-
-    fn explain(&mut self, _layout: &iced::Layout<'_>, _color: Color) {}
-}

src/element.rs

@@ -1,6 +1,8 @@
 use stretch::{geometry, result};
 
-use crate::{Event, Hasher, Layout, MouseCursor, Node, Point, Widget};
+use crate::{
+    renderer, Event, Hasher, Layout, MouseCursor, Node, Point, Widget,
+};
 
 /// A generic [`Widget`].
 ///
@@ -29,7 +31,7 @@ impl<'a, Message, Renderer> Element<'a, Message, Renderer> {
     /// Create a new [`Element`] containing the given [`Widget`].
     ///
     /// [`Element`]: struct.Element.html
-    /// [`Widget`]: trait.Widget.html
+    /// [`Widget`]: widget/trait.Widget.html
     pub fn new(
         widget: impl Widget<Message, Renderer> + 'a,
     ) -> Element<'a, Message, Renderer> {
@@ -72,7 +74,7 @@ impl<'a, Message, Renderer> Element<'a, Message, Renderer> {
     ) -> Element<'a, Message, Renderer>
     where
         Message: 'static,
-        Renderer: 'a + crate::Renderer,
+        Renderer: 'a + renderer::Debugger,
     {
         Element {
             widget: Box::new(Explain::new(self, color)),
@@ -160,14 +162,14 @@ where
     }
 }
 
-struct Explain<'a, Message, Renderer: crate::Renderer> {
+struct Explain<'a, Message, Renderer: renderer::Debugger> {
     element: Element<'a, Message, Renderer>,
     color: Renderer::Color,
 }
 
 impl<'a, Message, Renderer> std::fmt::Debug for Explain<'a, Message, Renderer>
 where
-    Renderer: crate::Renderer,
+    Renderer: renderer::Debugger,
 {
     fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
         f.debug_struct("Explain")
@@ -178,7 +180,7 @@ where
 
 impl<'a, Message, Renderer> Explain<'a, Message, Renderer>
 where
-    Renderer: crate::Renderer,
+    Renderer: renderer::Debugger,
 {
     fn new(
         element: Element<'a, Message, Renderer>,
@@ -191,7 +193,7 @@ where
 impl<'a, Message, Renderer> Widget<Message, Renderer>
     for Explain<'a, Message, Renderer>
 where
-    Renderer: crate::Renderer,
+    Renderer: renderer::Debugger,
 {
     fn node(&self, renderer: &Renderer) -> Node {
         self.element.widget.node(renderer)

src/layout.rs

@@ -9,9 +9,9 @@ use crate::{Point, Rectangle, Vector};
 /// [`Widget::node`].
 ///
 /// [`Node`]: struct.Node.html
-/// [`Widget::on_event`]: trait.Widget.html#method.on_event
-/// [`Widget::draw`]: trait.Widget.html#tymethod.draw
-/// [`Widget::node`]: trait.Widget.html#tymethod.node
+/// [`Widget::on_event`]: widget/trait.Widget.html#method.on_event
+/// [`Widget::draw`]: widget/trait.Widget.html#tymethod.draw
+/// [`Widget::node`]: widget/trait.Widget.html#tymethod.node
 #[derive(Debug)]
 pub struct Layout<'a> {
     layout: &'a result::Layout,
@@ -39,7 +39,7 @@ impl<'a> Layout<'a> {
     /// [`Node`].
     ///
     /// [`Layout`]: struct.Layout.html
-    /// [`Rectangle`]: ../../graphics/struct.Rectangle.html
+    /// [`Rectangle`]: struct.Rectangle.html
     /// [`Node`]: struct.Node.html
     pub fn bounds(&self) -> Rectangle<f32> {
         Rectangle {

src/lib.rs

@@ -197,6 +197,7 @@
 #![deny(unsafe_code)]
 #![deny(rust_2018_idioms)]
 pub mod input;
+pub mod renderer;
 pub mod widget;
 
 mod element;
@@ -207,7 +208,6 @@ mod mouse_cursor;
 mod node;
 mod point;
 mod rectangle;
-mod renderer;
 mod style;
 mod user_interface;
 mod vector;
@@ -223,7 +223,6 @@ pub use mouse_cursor::MouseCursor;
 pub use node::Node;
 pub use point::Point;
 pub use rectangle::Rectangle;
-pub use renderer::Renderer;
 pub use style::{Align, Justify, Style};
 pub use user_interface::{Cache, UserInterface};
 pub(crate) use vector::Vector;

src/node.rs

@@ -8,9 +8,9 @@ use crate::{Number, Size, Style};
 /// runtime obtains a [`Node`] by calling [`Widget::node`].
 ///
 /// [`Style`]: struct.Style.html
-/// [`Widget`]: trait.Widget.html
+/// [`Widget`]: widget/trait.Widget.html
 /// [`Node`]: struct.Node.html
-/// [`Widget::node`]: trait.Widget.html#tymethod.node
+/// [`Widget::node`]: widget/trait.Widget.html#tymethod.node
 /// [`Layout`]: struct.Layout.html
 #[derive(Debug)]
 pub struct Node(pub(crate) node::Node);
@@ -47,7 +47,7 @@ impl Node {
     ///
     /// [`Node`]: struct.Node.html
     /// [`Style`]: struct.Style.html
-    /// [`Widget`]: trait.Widget.html
+    /// [`Widget`]: widget/trait.Widget.html
     pub fn with_measure<F>(style: Style, measure: F) -> Node
     where
         F: 'static + Fn(Size<Number>) -> Size<f32>,

src/renderer.rs

@@ -1,6 +1,33 @@
+//! Write your own renderer!
+//!
+//! There is not a common entrypoint or trait for a __renderer__ in Iced.
+//! Instead, every [`Widget`] constrains its generic `Renderer` type as
+//! necessary.
+//!
+//! This approach is flexible and composable. For instance, the
+//! [`Text`] widget only needs a [`text::Renderer`] while a [`Checkbox`] widget
+//! needs both a [`text::Renderer`] and a [`checkbox::Renderer`], reusing logic.
+//!
+//! In the end, a __renderer__ satisfying all the constraints is
+//! needed to build a [`UserInterface`].
+//!
+//! [`Widget`]: ../widget/trait.Widget.html
+//! [`UserInterface`]: ../struct.UserInterface.html
+//! [`Text`]: ../widget/text/struct.Text.html
+//! [`text::Renderer`]: ../widget/text/trait.Renderer.html
+//! [`Checkbox`]: ../widget/checkbox/struct.Checkbox.html
+//! [`checkbox::Renderer`]: ../widget/checkbox/trait.Renderer.html
 use crate::Layout;
 
-pub trait Renderer {
+/// A renderer able to graphically explain a [`Layout`].
+///
+/// [`Layout`]: ../struct.Layout.html
+pub trait Debugger {
+    /// The color type that will be used to configure the _explanation_.
+    ///
+    /// This is the type that will be asked in [`Element::explain`].
+    ///
+    /// [`Element::explain`]: ../struct.Element.html#method.explain
     type Color: Copy;
 
     /// Explains the [`Layout`] of an [`Element`] for debugging purposes.

src/widget.rs

@@ -2,8 +2,8 @@
 //!
 //! # Built-in widgets
 //! Every built-in drawable widget has its own module with a `Renderer` trait
-//! that must be implemented by an [`iced::Renderer`] before being able to use
-//! it as a [`Widget`].
+//! that must be implemented by a [renderer] before being able to use it as
+//! a [`Widget`].
 //!
 //! # Custom widgets
 //! If you want to implement a custom widget, you simply need to implement the
@@ -19,7 +19,7 @@
 //! ```
 //!
 //! [`Widget`]: trait.Widget.html
-//! [`iced::Renderer`]: ../trait.Renderer.html
+//! [renderer]: ../renderer/index.html
 mod column;
 mod row;
 

src/widget/button.rs

@@ -16,11 +16,10 @@ use std::hash::Hash;
 
 /// A generic widget that produces a message when clicked.
 ///
-/// It implements [`Widget`] when the associated [`core::Renderer`] implements
-/// the [`button::Renderer`] trait.
+/// It implements [`Widget`] when the associated `Renderer` implements the
+/// [`button::Renderer`] trait.
 ///
-/// [`Widget`]: ../../core/trait.Widget.html
-/// [`core::Renderer`]: ../../core/trait.Renderer.html
+/// [`Widget`]: ../trait.Widget.html
 /// [`button::Renderer`]: trait.Renderer.html
 ///
 /// # Example

src/widget/checkbox.rs

@@ -10,11 +10,10 @@ use crate::{
 
 /// A box that can be checked.
 ///
-/// It implements [`Widget`] when the [`core::Renderer`] implements the
+/// It implements [`Widget`] when the associated `Renderer` implements the
 /// [`checkbox::Renderer`] trait.
 ///
-/// [`Widget`]: ../../core/trait.Widget.html
-/// [`core::Renderer`]: ../../core/trait.Renderer.html
+/// [`Widget`]: ../trait.Widget.html
 /// [`checkbox::Renderer`]: trait.Renderer.html
 ///
 /// # Example

src/widget/radio.rs

@@ -10,11 +10,10 @@ use std::hash::Hash;
 
 /// A circular button representing a choice.
 ///
-/// It implements [`Widget`] when the [`core::Renderer`] implements the
+/// It implements [`Widget`] when the associated `Renderer` implements the
 /// [`radio::Renderer`] trait.
 ///
-/// [`Widget`]: ../../core/trait.Widget.html
-/// [`core::Renderer`]: ../../core/trait.Renderer.html
+/// [`Widget`]: ../trait.Widget.html
 /// [`radio::Renderer`]: trait.Renderer.html
 ///
 /// # Example

src/widget/slider.rs

@@ -18,12 +18,11 @@ use crate::{
 ///
 /// A [`Slider`] will try to fill the horizontal space of its container.
 ///
-/// It implements [`Widget`] when the associated [`core::Renderer`] implements
-/// the [`slider::Renderer`] trait.
+/// It implements [`Widget`] when the associated `Renderer` implements the
+/// [`slider::Renderer`] trait.
 ///
 /// [`Slider`]: struct.Slider.html
-/// [`Widget`]: ../../core/trait.Widget.html
-/// [`core::Renderer`]: ../../core/trait.Renderer.html
+/// [`Widget`]: ../trait.Widget.html
 /// [`slider::Renderer`]: trait.Renderer.html
 ///
 /// # Example

src/widget/text.rs

@@ -7,11 +7,10 @@ use std::hash::Hash;
 
 /// A fragment of text.
 ///
-/// It implements [`Widget`] when the associated [`core::Renderer`] implements
-/// the [`text::Renderer`] trait.
+/// It implements [`Widget`] when the associated `Renderer` implements the
+/// [`text::Renderer`] trait.
 ///
-/// [`Widget`]: ../../core/trait.Widget.html
-/// [`core::Renderer`]: ../../core/trait.Renderer.html
+/// [`Widget`]: ../trait.Widget.html
 /// [`text::Renderer`]: trait.Renderer.html
 ///
 /// # Example