Write documentation for the new `overlay` API

8 files changed, 197 insertions, 24 deletions

diff --git a/native/src/element.rs b/native/src/element.rs
index db95919a..a1320f18 100644
--- a/native/src/element.rs
+++ b/native/src/element.rs
@@ -24,7 +24,7 @@ impl<'a, Message, Renderer> Element<'a, Message, Renderer>
 where
     Renderer: crate::Renderer,
 {
-    /// Create a new [`Element`] containing the given [`Widget`].
+    /// Creates a new [`Element`] containing the given [`Widget`].
     ///
     /// [`Element`]: struct.Element.html
     /// [`Widget`]: widget/trait.Widget.html
@@ -273,6 +273,9 @@ where
         self.widget.hash_layout(state);
     }
 
+    /// Returns the overlay of the [`Element`], if there is any.
+    ///
+    /// [`Element`]: struct.Element.html
     pub fn overlay<'b>(
         &'b mut self,
         layout: Layout<'_>,
diff --git a/native/src/lib.rs b/native/src/lib.rs
index ea328592..067e3c0a 100644
--- a/native/src/lib.rs
+++ b/native/src/lib.rs
@@ -30,8 +30,8 @@
 //! [`Widget`]: widget/trait.Widget.html
 //! [`UserInterface`]: struct.UserInterface.html
 //! [renderer]: renderer/index.html
-//#![deny(missing_docs)]
-//#![deny(missing_debug_implementations)]
+#![deny(missing_docs)]
+#![deny(missing_debug_implementations)]
 #![deny(unused_results)]
 #![forbid(unsafe_code)]
 #![forbid(rust_2018_idioms)]
diff --git a/native/src/overlay.rs b/native/src/overlay.rs
index b6cbbec3..7c3bec32 100644
--- a/native/src/overlay.rs
+++ b/native/src/overlay.rs
@@ -1,3 +1,4 @@
+//! Display interactive elements on top of other widgets.
 mod element;
 
 pub mod menu;
@@ -7,10 +8,19 @@ pub use menu::Menu;
 
 use crate::{layout, Clipboard, Event, Hasher, Layout, Point, Size};
 
+/// An interactive component that can be displayed on top of other widgets.
 pub trait Overlay<Message, Renderer>
 where
     Renderer: crate::Renderer,
 {
+    /// Returns the layout [`Node`] of the [`Overlay`].
+    ///
+    /// This [`Node`] is used by the runtime to compute the [`Layout`] of the
+    /// user interface.
+    ///
+    /// [`Node`]: ../layout/struct.Node.html
+    /// [`Widget`]: trait.Overlay.html
+    /// [`Layout`]: ../layout/struct.Layout.html
     fn layout(
         &self,
         renderer: &Renderer,
@@ -18,6 +28,9 @@ where
         position: Point,
     ) -> layout::Node;
 
+    /// Draws the [`Overlay`] using the associated `Renderer`.
+    ///
+    /// [`Overlay`]: trait.Overlay.html
     fn draw(
         &self,
         renderer: &mut Renderer,
@@ -26,8 +39,38 @@ where
         cursor_position: Point,
     ) -> Renderer::Output;
 
+    /// Computes the _layout_ hash of the [`Overlay`].
+    ///
+    /// The produced hash is used by the runtime to decide if the [`Layout`]
+    /// needs to be recomputed between frames. Therefore, to ensure maximum
+    /// efficiency, the hash should only be affected by the properties of the
+    /// [`Overlay`] that can affect layouting.
+    ///
+    /// For example, the [`Text`] widget does not hash its color property, as
+    /// its value cannot affect the overall [`Layout`] of the user interface.
+    ///
+    /// [`Overlay`]: trait.Overlay.html
+    /// [`Layout`]: ../layout/struct.Layout.html
+    /// [`Text`]: text/struct.Text.html
     fn hash_layout(&self, state: &mut Hasher, position: Point);
 
+    /// Processes a runtime [`Event`].
+    ///
+    /// It receives:
+    ///   * an [`Event`] describing user interaction
+    ///   * the computed [`Layout`] of the [`Overlay`]
+    ///   * the current cursor position
+    ///   * a mutable `Message` list, allowing the [`Overlay`] to produce
+    ///   new messages based on user interaction.
+    ///   * the `Renderer`
+    ///   * a [`Clipboard`], if available
+    ///
+    /// By default, it does nothing.
+    ///
+    /// [`Event`]: ../enum.Event.html
+    /// [`Overlay`]: trait.Widget.html
+    /// [`Layout`]: ../layout/struct.Layout.html
+    /// [`Clipboard`]: ../trait.Clipboard.html
     fn on_event(
         &mut self,
         _event: Event,
diff --git a/native/src/overlay/element.rs b/native/src/overlay/element.rs
index a159e3c1..3d532126 100644
--- a/native/src/overlay/element.rs
+++ b/native/src/overlay/element.rs
@@ -3,6 +3,9 @@ pub use crate::Overlay;
 use crate::{layout, Clipboard, Event, Hasher, Layout, Point, Size, Vector};
 use std::rc::Rc;
 
+/// A generic [`Overlay`].
+///
+/// [`Overlay`]: trait.Overlay.html
 #[allow(missing_debug_implementations)]
 pub struct Element<'a, Message, Renderer> {
     position: Point,
@@ -13,6 +16,10 @@ impl<'a, Message, Renderer> Element<'a, Message, Renderer>
 where
     Renderer: crate::Renderer,
 {
+    /// Creates a new [`Element`] containing the given [`Overlay`].
+    ///
+    /// [`Element`]: struct.Element.html
+    /// [`Overlay`]: trait.Overlay.html
     pub fn new(
         position: Point,
         overlay: Box<dyn Overlay<Message, Renderer> + 'a>,
@@ -20,11 +27,17 @@ where
         Self { position, overlay }
     }
 
+    /// Translates the [`Element`].
+    ///
+    /// [`Element`]: struct.Element.html
     pub fn translate(mut self, translation: Vector) -> Self {
         self.position = self.position + translation;
         self
     }
 
+    /// Applies a transformation to the produced message of the [`Element`].
+    ///
+    /// [`Element`]: struct.Element.html
     pub fn map<B>(self, f: Rc<dyn Fn(Message) -> B>) -> Element<'a, B, Renderer>
     where
         Message: 'a,
@@ -37,25 +50,16 @@ where
         }
     }
 
+    /// Computes the layout of the [`Element`] in the given bounds.
+    ///
+    /// [`Element`]: struct.Element.html
     pub fn layout(&self, renderer: &Renderer, bounds: Size) -> layout::Node {
         self.overlay.layout(renderer, bounds, self.position)
     }
 
-    pub fn draw(
-        &self,
-        renderer: &mut Renderer,
-        defaults: &Renderer::Defaults,
-        layout: Layout<'_>,
-        cursor_position: Point,
-    ) -> Renderer::Output {
-        self.overlay
-            .draw(renderer, defaults, layout, cursor_position)
-    }
-
-    pub fn hash_layout(&self, state: &mut Hasher) {
-        self.overlay.hash_layout(state, self.position);
-    }
-
+    /// Processes a runtime [`Event`].
+    ///
+    /// [`Event`]: enum.Event.html
     pub fn on_event(
         &mut self,
         event: Event,
@@ -74,6 +78,28 @@ where
             clipboard,
         )
     }
+
+    /// Draws the [`Element`] and its children using the given [`Layout`].
+    ///
+    /// [`Element`]: struct.Element.html
+    /// [`Layout`]: layout/struct.Layout.html
+    pub fn draw(
+        &self,
+        renderer: &mut Renderer,
+        defaults: &Renderer::Defaults,
+        layout: Layout<'_>,
+        cursor_position: Point,
+    ) -> Renderer::Output {
+        self.overlay
+            .draw(renderer, defaults, layout, cursor_position)
+    }
+
+    /// Computes the _layout_ hash of the [`Element`].
+    ///
+    /// [`Element`]: struct.Element.html
+    pub fn hash_layout(&self, state: &mut Hasher) {
+        self.overlay.hash_layout(state, self.position);
+    }
 }
 
 struct Map<'a, A, B, Renderer> {
diff --git a/native/src/overlay/menu.rs b/native/src/overlay/menu.rs
index 8c5daae1..0d4bc63c 100644
--- a/native/src/overlay/menu.rs
+++ b/native/src/overlay/menu.rs
@@ -1,9 +1,12 @@
+//! Build and show dropdown menus.
 use crate::{
     container, layout, mouse, overlay, scrollable, text, Clipboard, Container,
     Element, Event, Hasher, Layout, Length, Point, Rectangle, Scrollable, Size,
     Vector, Widget,
 };
 
+/// A list of selectable options.
+#[allow(missing_debug_implementations)]
 pub struct Menu<'a, T, Message, Renderer: self::Renderer> {
     state: &'a mut State,
     options: &'a [T],
@@ -21,6 +24,11 @@ where
     Message: 'a,
     Renderer: self::Renderer + 'a,
 {
+    /// Creates a new [`Menu`] with the given [`State`], a list of options, and
+    /// the message to produced when an option is selected.
+    ///
+    /// [`Menu`]: struct.Menu.html
+    /// [`State`]: struct.State.html
     pub fn new(
         state: &'a mut State,
         options: &'a [T],
@@ -38,26 +46,41 @@ where
         }
     }
 
+    /// Sets the width of the [`Menu`].
+    ///
+    /// [`Menu`]: struct.Menu.html
     pub fn width(mut self, width: u16) -> Self {
         self.width = width;
         self
     }
 
+    /// Sets the padding of the [`Menu`].
+    ///
+    /// [`Menu`]: struct.Menu.html
     pub fn padding(mut self, padding: u16) -> Self {
         self.padding = padding;
         self
     }
 
+    /// Sets the text size of the [`Menu`].
+    ///
+    /// [`Menu`]: struct.Menu.html
     pub fn text_size(mut self, text_size: u16) -> Self {
         self.text_size = Some(text_size);
         self
     }
 
+    /// Sets the font of the [`Menu`].
+    ///
+    /// [`Menu`]: struct.Menu.html
     pub fn font(mut self, font: Renderer::Font) -> Self {
         self.font = font;
         self
     }
 
+    /// Sets the style of the [`Menu`].
+    ///
+    /// [`Menu`]: struct.Menu.html
     pub fn style(
         mut self,
         style: impl Into<<Renderer as self::Renderer>::Style>,
@@ -66,6 +89,14 @@ where
         self
     }
 
+    /// Turns the [`Menu`] into an overlay [`Element`] at the given target
+    /// position.
+    ///
+    /// The `target_height` will be used to display the menu either on top
+    /// of the target or under it, depending on the screen position and the
+    /// dimensions of the [`Menu`].
+    ///
+    /// [`Menu`]: struct.Menu.html
     pub fn overlay(
         self,
         position: Point,
@@ -78,7 +109,10 @@ where
     }
 }
 
-#[derive(Default)]
+/// The local state of a [`Menu`].
+///
+/// [`Menu`]: struct.Menu.html
+#[derive(Debug, Clone, Default)]
 pub struct State {
     scrollable: scrollable::State,
     hovered_option: Option<usize>,
@@ -86,10 +120,16 @@ pub struct State {
 }
 
 impl State {
+    /// Returns whether the [`Menu`] is currently open or not.
+    ///
+    /// [`Menu`]: struct.Menu.html
     pub fn is_open(&self) -> bool {
         self.is_open
     }
 
+    /// Opens the [`Menu`] with the given option hovered by default.
+    ///
+    /// [`Menu`]: struct.Menu.html
     pub fn open(&mut self, hovered_option: Option<usize>) {
         self.is_open = true;
         self.hovered_option = hovered_option;
@@ -367,11 +407,26 @@ where
     }
 }
 
+/// The renderer of a [`Menu`].
+///
+/// Your [renderer] will need to implement this trait before being
+/// able to use a [`Menu`] in your user interface.
+///
+/// [`Menu`]: struct.Menu.html
+/// [renderer]: ../../renderer/index.html
 pub trait Renderer:
     scrollable::Renderer + container::Renderer + text::Renderer
 {
+    /// The [`Menu`] style supported by this renderer.
+    ///
+    /// [`Menu`]: struct.Menu.html
     type Style: Default + Clone;
 
+    /// Decorates a the list of options of a [`Menu`].
+    ///
+    /// This method can be used to draw a background for the [`Menu`].
+    ///
+    /// [`Menu`]: struct.Menu.html
     fn decorate(
         &mut self,
         bounds: Rectangle,
@@ -380,6 +435,9 @@ pub trait Renderer:
         primitive: Self::Output,
     ) -> Self::Output;
 
+    /// Draws the list of options of a [`Menu`].
+    ///
+    /// [`Menu`]: struct.Menu.html
     fn draw<T: ToString>(
         &mut self,
         bounds: Rectangle,
diff --git a/native/src/renderer.rs b/native/src/renderer.rs
index 29a091a4..d986141f 100644
--- a/native/src/renderer.rs
+++ b/native/src/renderer.rs
@@ -57,6 +57,8 @@ pub trait Renderer: Sized {
         element.layout(self, limits)
     }
 
+    /// Overlays the `overlay` output with the given bounds on top of the `base`
+    /// output.
     fn overlay(
         &mut self,
         base: Self::Output,
diff --git a/native/src/widget.rs b/native/src/widget.rs
index a7f279ed..931b4739 100644
--- a/native/src/widget.rs
+++ b/native/src/widget.rs
@@ -179,6 +179,9 @@ where
     ) {
     }
 
+    /// Returns the overlay of the [`Element`], if there is any.
+    ///
+    /// [`Element`]: struct.Element.html
     fn overlay(
         &mut self,
         _layout: Layout<'_>,
diff --git a/native/src/widget/combo_box.rs b/native/src/widget/combo_box.rs
index a9f0e6ed..fefaf8ff 100644
--- a/native/src/widget/combo_box.rs
+++ b/native/src/widget/combo_box.rs
@@ -1,3 +1,4 @@
+//! Display a dropdown list of selectable values.
 use crate::{
     layout, mouse, overlay,
     overlay::menu::{self, Menu},
@@ -6,6 +7,8 @@ use crate::{
 };
 use std::borrow::Cow;
 
+/// A widget for selecting a single value from a list of options.
+#[allow(missing_debug_implementations)]
 pub struct ComboBox<'a, T, Message, Renderer: self::Renderer>
 where
     [T]: ToOwned<Owned = Vec<T>>,
@@ -22,7 +25,10 @@ where
     is_open: bool,
 }
 
-#[derive(Default)]
+/// The local state of a [`ComboBox`].
+///
+/// [`ComboBox`]: struct.ComboBox.html
+#[derive(Debug, Clone, Default)]
 pub struct State {
     menu: menu::State,
 }
@@ -33,6 +39,12 @@ where
     T: ToString,
     [T]: ToOwned<Owned = Vec<T>>,
 {
+    /// Creates a new [`ComboBox`] with the given [`State`], a list of options,
+    /// the current selected value, and the message to produce when an option is
+    /// selected.
+    ///
+    /// [`ComboBox`]: struct.ComboBox.html
+    /// [`State`]: struct.State.html
     pub fn new(
         state: &'a mut State,
         options: impl Into<Cow<'a, [T]>>,
@@ -57,7 +69,7 @@ where
 
     /// Sets the width of the [`ComboBox`].
     ///
-    /// [`ComboBox`]: struct.Button.html
+    /// [`ComboBox`]: struct.ComboBox.html
     pub fn width(mut self, width: Length) -> Self {
         self.width = width;
         self
@@ -65,17 +77,23 @@ where
 
     /// Sets the padding of the [`ComboBox`].
     ///
-    /// [`ComboBox`]: struct.Button.html
+    /// [`ComboBox`]: struct.ComboBox.html
     pub fn padding(mut self, padding: u16) -> Self {
         self.padding = padding;
         self
     }
 
+    /// Sets the text size of the [`ComboBox`].
+    ///
+    /// [`ComboBox`]: struct.ComboBox.html
     pub fn text_size(mut self, size: u16) -> Self {
         self.text_size = Some(size);
         self
     }
 
+    /// Sets the font of the [`ComboBox`].
+    ///
+    /// [`ComboBox`]: struct.ComboBox.html
     pub fn font(mut self, font: Renderer::Font) -> Self {
         self.font = font;
         self
@@ -247,15 +265,35 @@ where
     }
 }
 
+/// The renderer of a [`ComboBox`].
+///
+/// Your [renderer] will need to implement this trait before being
+/// able to use a [`ComboBox`] in your user interface.
+///
+/// [`ComboBox`]: struct.ComboBox.html
+/// [renderer]: ../../renderer/index.html
 pub trait Renderer: text::Renderer + menu::Renderer {
-    type Style: Default;
-
+    /// The default padding of a [`ComboBox`].
+    ///
+    /// [`ComboBox`]: struct.ComboBox.html
     const DEFAULT_PADDING: u16;
 
+    /// The [`ComboBox`] style supported by this renderer.
+    ///
+    /// [`ComboBox`]: struct.ComboBox.html
+    type Style: Default;
+
+    /// Returns the style of the [`Menu`] of the [`ComboBox`].
+    ///
+    /// [`Menu`]: ../../overlay/menu/struct.Menu.html
+    /// [`ComboBox`]: struct.ComboBox.html
     fn menu_style(
         style: &<Self as Renderer>::Style,
     ) -> <Self as menu::Renderer>::Style;
 
+    /// Draws a [`ComboBox`].
+    ///
+    /// [`ComboBox`]: struct.ComboBox.html
     fn draw(
         &mut self,
         bounds: Rectangle,