Write missing documentation in `iced_native`

3 files changed, 55 insertions, 0 deletions

diff --git a/native/src/widget/operation.rs b/native/src/widget/operation.rs
index 4a075da9..ef636aa2 100644
--- a/native/src/widget/operation.rs
+++ b/native/src/widget/operation.rs
@@ -1,3 +1,4 @@
+//! Query or update internal widget state.
 pub mod focusable;
 pub mod scrollable;
 
@@ -6,24 +7,54 @@ pub use scrollable::Scrollable;
 
 use crate::widget::Id;
 
+use std::fmt;
+
+/// A piece of logic that can traverse the widget tree of an application in
+/// order to query or update some widget state.
 pub trait Operation<T> {
+    /// Operates on a widget that contains other widgets.
+    ///
+    /// The `operate_on_children` function can be called to return control to
+    /// the widget tree and keep traversing it.
     fn container(
         &mut self,
         id: Option<&Id>,
         operate_on_children: &mut dyn FnMut(&mut dyn Operation<T>),
     );
 
+    /// Operates on a widget that can be focused.
     fn focusable(&mut self, _state: &mut dyn Focusable, _id: Option<&Id>) {}
 
+    /// Operates on a widget that can be scrolled.
     fn scrollable(&mut self, _state: &mut dyn Scrollable, _id: Option<&Id>) {}
 
+    /// Finishes the [`Operation`] and returns its [`Outcome`].
     fn finish(&self) -> Outcome<T> {
         Outcome::None
     }
 }
 
+/// The result of an [`Operation`].
 pub enum Outcome<T> {
+    /// The [`Operation`] produced no result.
     None,
+
+    /// The [`Operation`] produced some result.
     Some(T),
+
+    /// The [`Operation`] needs to be followed by another [`Operation`].
     Chain(Box<dyn Operation<T>>),
 }
+
+impl<T> fmt::Debug for Outcome<T>
+where
+    T: fmt::Debug,
+{
+    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
+        match self {
+            Self::None => write!(f, "Outcome::None"),
+            Self::Some(output) => write!(f, "Outcome::Some({:?})", output),
+            Self::Chain(_) => write!(f, "Outcome::Chain(...)"),
+        }
+    }
+}
diff --git a/native/src/widget/operation/focusable.rs b/native/src/widget/operation/focusable.rs
index 20a73291..d20bfef9 100644
--- a/native/src/widget/operation/focusable.rs
+++ b/native/src/widget/operation/focusable.rs
@@ -1,18 +1,30 @@
+//! Operate on widgets that can be focused.
 use crate::widget::operation::{Operation, Outcome};
 use crate::widget::Id;
 
+/// The internal state of a widget that can be focused.
 pub trait Focusable {
+    /// Returns whether the widget is focused or not.
     fn is_focused(&self) -> bool;
+
+    /// Focuses the widget.
     fn focus(&mut self);
+
+    /// Unfocuses the widget.
     fn unfocus(&mut self);
 }
 
+/// A summary of the focusable widgets present on a widget tree.
 #[derive(Debug, Clone, Copy, PartialEq, Eq, Default)]
 pub struct Count {
+    /// The index of the current focused widget, if any.
     focused: Option<usize>,
+
+    /// The total amount of focusable widgets.
     total: usize,
 }
 
+/// Produces an [`Operation`] that focuses the widget with the given [`Id`].
 pub fn focus<T>(target: Id) -> impl Operation<T> {
     struct Focus {
         target: Id,
@@ -42,6 +54,7 @@ pub fn focus<T>(target: Id) -> impl Operation<T> {
     Focus { target }
 }
 
+/// Produces an [`Operation`] that generates a [`Count`].
 pub fn count<T, O>(f: fn(Count) -> O) -> impl Operation<T>
 where
     O: Operation<T> + 'static,
@@ -82,6 +95,9 @@ where
     }
 }
 
+/// Produces an [`Operation`] that searches for the current focuses widget, and
+/// - if found, focuses the previous focusable widget.
+/// - if not found, focuses the last focusable widget.
 pub fn focus_previous<T>() -> impl Operation<T> {
     struct FocusPrevious {
         count: Count,
@@ -118,6 +134,9 @@ pub fn focus_previous<T>() -> impl Operation<T> {
     count(|count| FocusPrevious { count, current: 0 })
 }
 
+/// Produces an [`Operation`] that searches for the current focuses widget, and
+/// - if found, focuses the next focusable widget.
+/// - if not found, focuses the first focusable widget.
 pub fn focus_next<T>() -> impl Operation<T> {
     struct FocusNext {
         count: Count,
diff --git a/native/src/widget/operation/scrollable.rs b/native/src/widget/operation/scrollable.rs
index ed609d67..2210137d 100644
--- a/native/src/widget/operation/scrollable.rs
+++ b/native/src/widget/operation/scrollable.rs
@@ -1,9 +1,14 @@
+//! Operate on widgets that can be scrolled.
 use crate::widget::{Id, Operation};
 
+/// The internal state of a widget that can be scrolled.
 pub trait Scrollable {
+    /// Snaps the scroll of the widget to the given `percentage`.
     fn snap_to(&mut self, percentage: f32);
 }
 
+/// Produces an [`Operation`] that snaps the widget with the given [`Id`] to
+/// the provided `percentage`.
 pub fn snap_to<T>(target: Id, percentage: f32) -> impl Operation<T> {
     struct SnapTo {
         target: Id,