Write documentation for iced_pure

pure/src/widget/button.rs

@@ -1,3 +1,4 @@
+//! Allow your users to perform actions by pressing a button.
 use crate::overlay;
 use crate::widget::tree::{self, Tree};
 use crate::{Element, Widget};
@@ -15,6 +16,40 @@ pub use iced_style::button::{Style, StyleSheet};
 
 use button::State;
 
+/// A generic widget that produces a message when pressed.
+///
+/// ```
+/// # type Button<'a, Message> =
+/// #     iced_pure::widget::Button<'a, Message, iced_native::renderer::Null>;
+/// #
+/// #[derive(Clone)]
+/// enum Message {
+///     ButtonPressed,
+/// }
+///
+/// let button = Button::new("Press me!").on_press(Message::ButtonPressed);
+/// ```
+///
+/// If a [`Button::on_press`] handler is not set, the resulting [`Button`] will
+/// be disabled:
+///
+/// ```
+/// # type Button<'a, Message> =
+/// #     iced_pure::widget::Button<'a, Message, iced_native::renderer::Null>;
+/// #
+/// #[derive(Clone)]
+/// enum Message {
+///     ButtonPressed,
+/// }
+///
+/// fn disabled_button<'a>() -> Button<'a, Message> {
+///     Button::new("I'm disabled!")
+/// }
+///
+/// fn enabled_button<'a>() -> Button<'a, Message> {
+///     disabled_button().on_press(Message::ButtonPressed)
+/// }
+/// ```
 pub struct Button<'a, Message, Renderer> {
     content: Element<'a, Message, Renderer>,
     on_press: Option<Message>,
@@ -25,6 +60,7 @@ pub struct Button<'a, Message, Renderer> {
 }
 
 impl<'a, Message, Renderer> Button<'a, Message, Renderer> {
+    /// Creates a new [`Button`] with the given content.
     pub fn new(content: impl Into<Element<'a, Message, Renderer>>) -> Self {
         Button {
             content: content.into(),

pure/src/widget/checkbox.rs

@@ -1,3 +1,4 @@
+//! Show toggle controls using checkboxes.
 use crate::widget::Tree;
 use crate::{Element, Widget};
 

pure/src/widget/column.rs

@@ -13,6 +13,7 @@ use iced_native::{
 
 use std::u32;
 
+/// A container that distributes its contents vertically.
 pub struct Column<'a, Message, Renderer> {
     spacing: u16,
     padding: Padding,
@@ -24,10 +25,12 @@ pub struct Column<'a, Message, Renderer> {
 }
 
 impl<'a, Message, Renderer> Column<'a, Message, Renderer> {
+    /// Creates an empty [`Column`].
     pub fn new() -> Self {
         Self::with_children(Vec::new())
     }
 
+    /// Creates a [`Column`] with the given elements.
     pub fn with_children(
         children: Vec<Element<'a, Message, Renderer>>,
     ) -> Self {
@@ -42,21 +45,29 @@ impl<'a, Message, Renderer> Column<'a, Message, Renderer> {
         }
     }
 
+    /// Sets the vertical spacing _between_ elements.
+    ///
+    /// Custom margins per element do not exist in iced. You should use this
+    /// method instead! While less flexible, it helps you keep spacing between
+    /// elements consistent.
     pub fn spacing(mut self, units: u16) -> Self {
         self.spacing = units;
         self
     }
 
+    /// Sets the [`Padding`] of the [`Column`].
     pub fn padding<P: Into<Padding>>(mut self, padding: P) -> Self {
         self.padding = padding.into();
         self
     }
 
+    /// Sets the width of the [`Column`].
     pub fn width(mut self, width: Length) -> Self {
         self.width = width;
         self
     }
 
+    /// Sets the height of the [`Column`].
     pub fn height(mut self, height: Length) -> Self {
         self.height = height;
         self
@@ -68,11 +79,13 @@ impl<'a, Message, Renderer> Column<'a, Message, Renderer> {
         self
     }
 
+    /// Sets the horizontal alignment of the contents of the [`Column`] .
     pub fn align_items(mut self, align: Alignment) -> Self {
         self.align_items = align;
         self
     }
 
+    /// Adds an element to the [`Column`].
     pub fn push(
         mut self,
         child: impl Into<Element<'a, Message, Renderer>>,

pure/src/widget/image.rs

@@ -1,3 +1,4 @@
+//! Display images in your user interface.
 use crate::widget::{Tree, Widget};
 use crate::Element;
 

pure/src/widget/pane_grid.rs

@@ -213,7 +213,7 @@ where
     fn diff(&self, tree: &mut Tree) {
         tree.diff_children_custom(
             &self.elements,
-            |(_, content), state| content.diff(state),
+            |state, (_, content)| content.diff(state),
             |(_, content)| content.state(),
         )
     }

pure/src/widget/pane_grid/content.rs

@@ -57,7 +57,7 @@ impl<'a, Message, Renderer> Content<'a, Message, Renderer>
 where
     Renderer: iced_native::Renderer,
 {
-    pub fn state(&self) -> Tree {
+    pub(super) fn state(&self) -> Tree {
         let children = if let Some(title_bar) = self.title_bar.as_ref() {
             vec![Tree::new(&self.body), title_bar.state()]
         } else {
@@ -70,7 +70,7 @@ where
         }
     }
 
-    pub fn diff(&self, tree: &mut Tree) {
+    pub(super) fn diff(&self, tree: &mut Tree) {
         if tree.children.len() == 2 {
             if let Some(title_bar) = self.title_bar.as_ref() {
                 title_bar.diff(&mut tree.children[1]);

pure/src/widget/pane_grid/title_bar.rs

@@ -81,7 +81,7 @@ impl<'a, Message, Renderer> TitleBar<'a, Message, Renderer>
 where
     Renderer: iced_native::Renderer,
 {
-    pub fn state(&self) -> Tree {
+    pub(super) fn state(&self) -> Tree {
         let children = if let Some(controls) = self.controls.as_ref() {
             vec![Tree::new(&self.content), Tree::new(controls)]
         } else {
@@ -94,7 +94,7 @@ where
         }
     }
 
-    pub fn diff(&self, tree: &mut Tree) {
+    pub(super) fn diff(&self, tree: &mut Tree) {
         if tree.children.len() == 2 {
             if let Some(controls) = self.controls.as_ref() {
                 tree.children[1].diff(controls);

pure/src/widget/progress_bar.rs

@@ -1,3 +1,4 @@
+//! Provide progress feedback to your users.
 use crate::widget::Tree;
 use crate::{Element, Widget};
 

pure/src/widget/radio.rs

@@ -1,3 +1,4 @@
+//! Create choices using radio buttons.
 use crate::widget::Tree;
 use crate::{Element, Widget};
 

pure/src/widget/row.rs

@@ -11,6 +11,7 @@ use iced_native::{
     Alignment, Clipboard, Length, Padding, Point, Rectangle, Shell,
 };
 
+/// A container that distributes its contents horizontally.
 pub struct Row<'a, Message, Renderer> {
     spacing: u16,
     padding: Padding,
@@ -21,10 +22,12 @@ pub struct Row<'a, Message, Renderer> {
 }
 
 impl<'a, Message, Renderer> Row<'a, Message, Renderer> {
+    /// Creates an empty [`Row`].
     pub fn new() -> Self {
         Self::with_children(Vec::new())
     }
 
+    /// Creates a [`Row`] with the given elements.
     pub fn with_children(
         children: Vec<Element<'a, Message, Renderer>>,
     ) -> Self {
@@ -38,31 +41,41 @@ impl<'a, Message, Renderer> Row<'a, Message, Renderer> {
         }
     }
 
+    /// Sets the horizontal spacing _between_ elements.
+    ///
+    /// Custom margins per element do not exist in iced. You should use this
+    /// method instead! While less flexible, it helps you keep spacing between
+    /// elements consistent.
     pub fn spacing(mut self, units: u16) -> Self {
         self.spacing = units;
         self
     }
 
+    /// Sets the [`Padding`] of the [`Row`].
     pub fn padding<P: Into<Padding>>(mut self, padding: P) -> Self {
         self.padding = padding.into();
         self
     }
 
+    /// Sets the width of the [`Row`].
     pub fn width(mut self, width: Length) -> Self {
         self.width = width;
         self
     }
 
+    /// Sets the height of the [`Row`].
     pub fn height(mut self, height: Length) -> Self {
         self.height = height;
         self
     }
 
+    /// Sets the vertical alignment of the contents of the [`Row`] .
     pub fn align_items(mut self, align: Alignment) -> Self {
         self.align_items = align;
         self
     }
 
+    /// Adds an [`Element`] to the [`Row`].
     pub fn push(
         mut self,
         child: impl Into<Element<'a, Message, Renderer>>,

pure/src/widget/rule.rs

@@ -1,3 +1,4 @@
+//! Display a horizontal or vertical rule for dividing content.
 use crate::widget::Tree;
 use crate::{Element, Widget};
 

pure/src/widget/scrollable.rs

@@ -1,3 +1,4 @@
+//! Navigate an endless amount of content with a scrollbar.
 use crate::overlay;
 use crate::widget::tree::{self, Tree};
 use crate::{Element, Widget};

pure/src/widget/svg.rs

@@ -1,3 +1,4 @@
+//! Display vector graphics in your application.
 use crate::widget::{Tree, Widget};
 use crate::Element;
 

pure/src/widget/text_input.rs

@@ -1,3 +1,4 @@
+//! Display fields that can be filled with text.
 use crate::widget::tree::{self, Tree};
 use crate::{Element, Widget};
 
@@ -15,10 +16,7 @@ pub use iced_style::text_input::{Style, StyleSheet};
 ///
 /// # Example
 /// ```
-/// # use iced_native::renderer::Null;
-/// # use iced_pure::widget::text_input;
-/// #
-/// # pub type TextInput<'a, Message> = iced_pure::widget::TextInput<'a, Message, Null>;
+/// # pub type TextInput<'a, Message> = iced_pure::widget::TextInput<'a, Message, iced_native::renderer::Null>;
 /// #[derive(Debug, Clone)]
 /// enum Message {
 ///     TextInputChanged(String),

pure/src/widget/toggler.rs

@@ -1,3 +1,4 @@
+//! Show toggle controls using togglers.
 use crate::widget::{Tree, Widget};
 use crate::Element;
 

pure/src/widget/tooltip.rs

@@ -32,7 +32,7 @@ where
     /// The default padding of a [`Tooltip`] drawn by this renderer.
     const DEFAULT_PADDING: u16 = 5;
 
-    /// Creates an empty [`Tooltip`].
+    /// Creates a new [`Tooltip`].
     ///
     /// [`Tooltip`]: struct.Tooltip.html
     pub fn new(

pure/src/widget/tree.rs

@@ -1,14 +1,24 @@
+//! Store internal widget state in a state tree to ensure continuity.
 use crate::Element;
 
 use std::any::{self, Any};
 
+/// A persistent state widget tree.
+///
+/// A [`Tree`] is normally associated with a specific widget in the widget tree.
 pub struct Tree {
+    /// The tag of the [`Tree`].
     pub tag: Tag,
+
+    /// The [`State`] of the [`Tree`].
     pub state: State,
+
+    /// The children of the root widget of the [`Tree`].
     pub children: Vec<Tree>,
 }
 
 impl Tree {
+    /// Creates an empty, stateless [`Tree`] with no children.
     pub fn empty() -> Self {
         Self {
             tag: Tag::stateless(),
@@ -17,6 +27,7 @@ impl Tree {
         }
     }
 
+    /// Creates a new [`Tree`] for the provided [`Element`].
     pub fn new<Message, Renderer>(
         element: &Element<'_, Message, Renderer>,
     ) -> Self {
@@ -27,6 +38,14 @@ impl Tree {
         }
     }
 
+    /// Reconciliates the current tree with the provided [`Element`].
+    ///
+    /// If the tag of the [`Element`] matches the tag of the [`Tree`], then the
+    /// [`Element`] proceeds with the reconciliation (i.e. [`Widget::diff`] is called).
+    ///
+    /// Otherwise, the whole [`Tree`] is recreated.
+    ///
+    /// [`Widget::diff`]: crate::Widget::diff
     pub fn diff<Message, Renderer>(
         &mut self,
         new: &Element<'_, Message, Renderer>,
@@ -38,21 +57,20 @@ impl Tree {
         }
     }
 
+    /// Reconciliates the children of the tree with the provided list of [`Element`].
     pub fn diff_children<Message, Renderer>(
         &mut self,
         new_children: &[Element<'_, Message, Renderer>],
     ) {
-        self.diff_children_custom(
-            new_children,
-            |new, child_state| child_state.diff(new),
-            Self::new,
-        )
+        self.diff_children_custom(new_children, Self::diff, Self::new)
     }
 
+    /// Reconciliates the children of the tree with the provided list of [`Element`] using custom
+    /// logic both for diffing and creating new widget state.
     pub fn diff_children_custom<T>(
         &mut self,
         new_children: &[T],
-        diff: impl Fn(&T, &mut Tree),
+        diff: impl Fn(&mut Tree, &T),
         new_state: impl Fn(&T) -> Self,
     ) {
         if self.children.len() > new_children.len() {
@@ -62,7 +80,7 @@ impl Tree {
         for (child_state, new) in
             self.children.iter_mut().zip(new_children.iter())
         {
-            diff(new, child_state);
+            diff(child_state, new);
         }
 
         if self.children.len() < new_children.len() {
@@ -73,10 +91,12 @@ impl Tree {
     }
 }
 
+/// The identifier of some widget state.
 #[derive(Debug, Clone, Copy, PartialOrd, Ord, PartialEq, Eq, Hash)]
 pub struct Tag(any::TypeId);
 
 impl Tag {
+    /// Creates a [`Tag`] for a state of type `T`.
     pub fn of<T>() -> Self
     where
         T: 'static,
@@ -84,17 +104,23 @@ impl Tag {
         Self(any::TypeId::of::<T>())
     }
 
+    /// Creates a [`Tag`] for a stateless widget.
     pub fn stateless() -> Self {
         Self::of::<()>()
     }
 }
 
+/// The internal [`State`] of a widget.
 pub enum State {
+    /// No meaningful internal state.
     None,
+
+    /// Some meaningful internal state.
     Some(Box<dyn Any>),
 }
 
 impl State {
+    /// Creates a new [`State`].
     pub fn new<T>(state: T) -> Self
     where
         T: 'static,
@@ -102,6 +128,10 @@ impl State {
         State::Some(Box::new(state))
     }
 
+    /// Downcasts the [`State`] to `T` and returns a reference to it.
+    ///
+    /// # Panics
+    /// This method will panic if the downcast fails or the [`State`] is [`State::None`].
     pub fn downcast_ref<T>(&self) -> &T
     where
         T: 'static,
@@ -114,6 +144,10 @@ impl State {
         }
     }
 
+    /// Downcasts the [`State`] to `T` and returns a mutable reference to it.
+    ///
+    /// # Panics
+    /// This method will panic if the downcast fails or the [`State`] is [`State::None`].
     pub fn downcast_mut<T>(&mut self) -> &mut T
     where
         T: 'static,