Write documentation for the new `overlay` API

2 files changed, 100 insertions, 16 deletions

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,