Write documentation for iced_pure

pure/src/widget.rs

@@ -1,3 +1,4 @@
+//! Use the built-in widgets or create your own.
 pub mod button;
 pub mod checkbox;
 pub mod container;
@@ -48,17 +49,28 @@ use iced_native::overlay;
 use iced_native::renderer;
 use iced_native::{Clipboard, Length, Point, Rectangle, Shell};
 
+/// A component that displays information and allows interaction.
+///
+/// If you want to build your own widgets, you will need to implement this
+/// trait.
 pub trait Widget<Message, Renderer> {
+    /// Returns the width of the [`Widget`].
     fn width(&self) -> Length;
 
+    /// Returns the height of the [`Widget`].
     fn height(&self) -> Length;
 
+    /// Returns the [`layout::Node`] of the [`Widget`].
+    ///
+    /// This [`layout::Node`] is used by the runtime to compute the [`Layout`] of the
+    /// user interface.
     fn layout(
         &self,
         renderer: &Renderer,
         limits: &layout::Limits,
     ) -> layout::Node;
 
+    /// Draws the [`Widget`] using the associated `Renderer`.
     fn draw(
         &self,
         state: &Tree,
@@ -69,31 +81,31 @@ pub trait Widget<Message, Renderer> {
         viewport: &Rectangle,
     );
 
+    /// Returns the [`Tag`] of the [`Widget`].
+    ///
+    /// [`Tag`]: tree::Tag
     fn tag(&self) -> tree::Tag {
         tree::Tag::stateless()
     }
 
+    /// Returns the [`State`] of the [`Widget`].
+    ///
+    /// [`State`]: tree::State
     fn state(&self) -> tree::State {
         tree::State::None
     }
 
+    /// Returns the state [`Tree`] of the children of the [`Widget`].
     fn children(&self) -> Vec<Tree> {
         Vec::new()
     }
 
+    /// Reconciliates the [`Widget`] with the provided [`Tree`].
     fn diff(&self, _tree: &mut Tree) {}
 
-    fn mouse_interaction(
-        &self,
-        _state: &Tree,
-        _layout: Layout<'_>,
-        _cursor_position: Point,
-        _viewport: &Rectangle,
-        _renderer: &Renderer,
-    ) -> mouse::Interaction {
-        mouse::Interaction::Idle
-    }
-
+    /// Processes a runtime [`Event`].
+    ///
+    /// By default, it does nothing.
     fn on_event(
         &mut self,
         _state: &mut Tree,
@@ -107,6 +119,21 @@ pub trait Widget<Message, Renderer> {
         event::Status::Ignored
     }
 
+    /// Returns the current [`mouse::Interaction`] of the [`Widget`].
+    ///
+    /// By default, it returns [`mouse::Interaction::Idle`].
+    fn mouse_interaction(
+        &self,
+        _state: &Tree,
+        _layout: Layout<'_>,
+        _cursor_position: Point,
+        _viewport: &Rectangle,
+        _renderer: &Renderer,
+    ) -> mouse::Interaction {
+        mouse::Interaction::Idle
+    }
+
+    /// Returns the overlay of the [`Widget`], if there is any.
     fn overlay<'a>(
         &'a self,
         _state: &'a mut Tree,