Merge pull request #65 from hecrj/improvement/docs

Documentation

1 files changed, 36 insertions, 12 deletions

diff --git a/web/src/element.rs b/web/src/element.rs
index a2b78c69..fcf0a4b6 100644
--- a/web/src/element.rs
+++ b/web/src/element.rs
@@ -3,29 +3,39 @@ use crate::{Bus, Color, Widget};
 use dodrio::bumpalo;
 use std::rc::Rc;
 
+/// A generic [`Widget`].
+///
+/// It is useful to build composable user interfaces that do not leak
+/// implementation details in their __view logic__.
+///
+/// If you have a [built-in widget], you should be able to use `Into<Element>`
+/// to turn it into an [`Element`].
+///
+/// [built-in widget]: widget/index.html
+/// [`Widget`]: widget/trait.Widget.html
+/// [`Element`]: struct.Element.html
+#[allow(missing_debug_implementations)]
 pub struct Element<'a, Message> {
     pub(crate) widget: Box<dyn Widget<Message> + 'a>,
 }
 
 impl<'a, Message> Element<'a, Message> {
+    /// Create a new [`Element`] containing the given [`Widget`].
+    ///
+    /// [`Element`]: struct.Element.html
+    /// [`Widget`]: widget/trait.Widget.html
     pub fn new(widget: impl Widget<Message> + 'a) -> Self {
         Self {
             widget: Box::new(widget),
         }
     }
 
-    pub fn node<'b>(
-        &self,
-        bump: &'b bumpalo::Bump,
-        bus: &Bus<Message>,
-    ) -> dodrio::Node<'b> {
-        self.widget.node(bump, bus)
-    }
-
-    pub fn explain(self, _color: Color) -> Element<'a, Message> {
-        self
-    }
-
+    /// Applies a transformation to the produced message of the [`Element`].
+    ///
+    /// This method is useful when you want to decouple different parts of your
+    /// UI and make them __composable__.
+    ///
+    /// [`Element`]: struct.Element.html
     pub fn map<F, B>(self, f: F) -> Element<'a, B>
     where
         Message: 'static,
@@ -36,6 +46,20 @@ impl<'a, Message> Element<'a, Message> {
             widget: Box::new(Map::new(self.widget, f)),
         }
     }
+
+    /// Marks the [`Element`] as _to-be-explained_.
+    pub fn explain(self, _color: Color) -> Element<'a, Message> {
+        self
+    }
+
+    /// Produces a VDOM node for the [`Element`].
+    pub fn node<'b>(
+        &self,
+        bump: &'b bumpalo::Bump,
+        bus: &Bus<Message>,
+    ) -> dodrio::Node<'b> {
+        self.widget.node(bump, bus)
+    }
 }
 
 struct Map<'a, A, B> {