Write missing documentation in `iced_native`

8 files changed, 81 insertions, 2 deletions

diff --git a/native/src/lib.rs b/native/src/lib.rs
index 73a6c624..13173901 100644
--- a/native/src/lib.rs
+++ b/native/src/lib.rs
@@ -32,8 +32,8 @@
     html_logo_url = "https://raw.githubusercontent.com/iced-rs/iced/9ab6923e943f784985e9ef9ca28b10278297225d/docs/logo.svg"
 )]
 #![deny(
-//    missing_debug_implementations,
-//    missing_docs,
+    missing_debug_implementations,
+    missing_docs,
     unused_results,
     clippy::extra_unused_lifetimes,
     clippy::from_over_into,
diff --git a/native/src/widget/action.rs b/native/src/widget/action.rs
index 21032dbb..766e902b 100644
--- a/native/src/widget/action.rs
+++ b/native/src/widget/action.rs
@@ -3,13 +3,17 @@ use crate::widget::Id;
 
 use iced_futures::MaybeSend;
 
+/// An operation to be performed on the widget tree.
+#[allow(missing_debug_implementations)]
 pub struct Action<T>(Box<dyn Operation<T>>);
 
 impl<T> Action<T> {
+    /// Creates a new [`Action`] with the given [`Operation`].
     pub fn new(operation: impl Operation<T> + 'static) -> Self {
         Self(Box::new(operation))
     }
 
+    /// Maps the output of an [`Action`] using the given function.
     pub fn map<A>(
         self,
         f: impl Fn(T) -> A + 'static + MaybeSend + Sync,
@@ -24,11 +28,13 @@ impl<T> Action<T> {
         }))
     }
 
+    /// Consumes the [`Action`] and returns the internal [`Operation`].
     pub fn into_operation(self) -> Box<dyn Operation<T>> {
         self.0
     }
 }
 
+#[allow(missing_debug_implementations)]
 struct Map<A, B> {
     operation: Box<dyn Operation<A>>,
     f: Box<dyn Fn(A) -> B>,
diff --git a/native/src/widget/id.rs b/native/src/widget/id.rs
index 4c0ab999..4b8fedf1 100644
--- a/native/src/widget/id.rs
+++ b/native/src/widget/id.rs
@@ -3,14 +3,19 @@ use std::sync::atomic::{self, AtomicUsize};
 
 static NEXT_ID: AtomicUsize = AtomicUsize::new(0);
 
+/// The identifier of a generic widget.
 #[derive(Debug, Clone, PartialEq, Eq, Hash)]
 pub struct Id(Internal);
 
 impl Id {
+    /// Creates a custom [`Id`].
     pub fn new(id: impl Into<borrow::Cow<'static, str>>) -> Self {
         Self(Internal::Custom(id.into()))
     }
 
+    /// Creates a unique [`Id`].
+    ///
+    /// This function produces a different [`Id`] every time it is called.
     pub fn unique() -> Self {
         let id = NEXT_ID.fetch_add(1, atomic::Ordering::Relaxed);
 
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,
diff --git a/native/src/widget/scrollable.rs b/native/src/widget/scrollable.rs
index b7a0b6ee..4ebb07a0 100644
--- a/native/src/widget/scrollable.rs
+++ b/native/src/widget/scrollable.rs
@@ -316,19 +316,26 @@ where
     }
 }
 
+/// The identifier of a [`Scrollable`].
 #[derive(Debug, Clone, PartialEq, Eq, Hash)]
 pub struct Id(widget::Id);
 
 impl Id {
+    /// Creates a custom [`Id`].
     pub fn new(id: impl Into<std::borrow::Cow<'static, str>>) -> Self {
         Self(widget::Id::new(id))
     }
 
+    /// Creates a unique [`Id`].
+    ///
+    /// This function produces a different [`Id`] every time it is called.
     pub fn unique() -> Self {
         Self(widget::Id::unique())
     }
 }
 
+/// Produces a [`Command`] that snaps the [`Scrollable`] with the given [`Id`]
+/// to the provided `percentage`.
 pub fn snap_to<Message: 'static>(id: Id, percentage: f32) -> Command<Message> {
     Command::widget(operation::scrollable::snap_to(id.0, percentage))
 }
diff --git a/native/src/widget/text_input.rs b/native/src/widget/text_input.rs
index e0216a5b..8ddbc734 100644
--- a/native/src/widget/text_input.rs
+++ b/native/src/widget/text_input.rs
@@ -314,19 +314,25 @@ where
     }
 }
 
+/// The identifier of a [`TextInput`].
 #[derive(Debug, Clone, PartialEq, Eq, Hash)]
 pub struct Id(widget::Id);
 
 impl Id {
+    /// Creates a custom [`Id`].
     pub fn new(id: impl Into<std::borrow::Cow<'static, str>>) -> Self {
         Self(widget::Id::new(id))
     }
 
+    /// Creates a unique [`Id`].
+    ///
+    /// This function produces a different [`Id`] every time it is called.
     pub fn unique() -> Self {
         Self(widget::Id::unique())
     }
 }
 
+/// Produces a [`Command`] that focuses the [`TextInput`] with the given [`Id`].
 pub fn focus<Message: 'static>(id: Id) -> Command<Message> {
     Command::widget(operation::focusable::focus(id.0))
 }