From 2118a726f8b6134820e1ca5b7b802fa1344e453a Mon Sep 17 00:00:00 2001
From: Héctor Ramón Jiménez <hector0193@gmail.com>
Date: Fri, 10 Jul 2020 02:39:12 +0200
Subject: Write documentation for the new `overlay` API

---
 native/src/overlay/element.rs | 56 +++++++++++++++++++++++++++++++------------
 1 file changed, 41 insertions(+), 15 deletions(-)

(limited to 'native/src/overlay/element.rs')

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> {
-- 
cgit