Write documentation for iced_selector

selector/src/find.rs

@@ -8,7 +8,12 @@ use crate::target::Candidate;
 
 use std::any::Any;
 
+/// An [`Operation`] that runs the [`Selector`] and stops after
+/// the first [`Output`](Selector::Output) is produced.
 pub type Find<S> = Finder<One<S>>;
+
+/// An [`Operation`] that runs the [`Selector`] for the entire
+/// widget tree and aggregates all of its [`Output`](Selector::Output).
 pub type FindAll<S> = Finder<All<S>>;
 
 #[derive(Debug)]

selector/src/lib.rs

@@ -1,4 +1,4 @@
-#![allow(missing_docs)]
+//! Select data from the widget tree.
 use iced_core as core;
 
 mod find;
@@ -10,13 +10,29 @@ pub use target::{Bounded, Candidate, Target, Text};
 use crate::core::Point;
 use crate::core::widget;
 
+/// A type that traverses the widget tree to "select" data and produce some output.
 pub trait Selector {
+    /// The output type of the [`Selector`].
+    ///
+    /// For most selectors, this will normally be a [`Target`]. However, some
+    /// may selectors may want to return a more limited type to encode the selection
+    /// guarantees in the type system.
+    ///
+    /// For instance, the implementations of [`String`] and [`str`] of [`Selector`]
+    /// return a [`target::Text`] instead of a generic [`Target`], since they are
+    /// guaranteed to only select text.
     type Output;
 
+    /// Performs a selection of the given [`Candidate`], if applicable.
+    ///
+    /// This method traverses the widget tree in depth-first order.
     fn select(&mut self, candidate: Candidate<'_>) -> Option<Self::Output>;
 
+    /// Returns a short description of the [`Selector`] for debugging purposes.
     fn description(&self) -> String;
 
+    /// Returns a [`widget::Operation`] that runs the [`Selector`] and stops after
+    /// the first [`Output`](Self::Output) is produced.
     fn find(self) -> Find<Self>
     where
         Self: Sized,
@@ -24,6 +40,8 @@ pub trait Selector {
         Find::new(find::One::new(self))
     }
 
+    /// Returns a [`widget::Operation`] that runs the [`Selector`] for the entire
+    /// widget tree and aggregates all of its [`Output`](Self::Output).
     fn find_all(self) -> FindAll<Self>
     where
         Self: Sized,

selector/src/target.rs

@@ -4,6 +4,8 @@ use crate::core::{Rectangle, Vector};
 
 use std::any::Any;
 
+/// A generic widget match produced during selection.
+#[allow(missing_docs)]
 #[derive(Debug, Clone, PartialEq)]
 pub enum Target {
     Container {
@@ -43,6 +45,7 @@ pub enum Target {
 }
 
 impl Target {
+    /// Returns the layout bounds of the [`Target`].
     pub fn bounds(&self) -> Rectangle {
         match self {
             Target::Container { bounds, .. }
@@ -54,6 +57,7 @@ impl Target {
         }
     }
 
+    /// Returns the visible bounds of the [`Target`], in screen coordinates.
     pub fn visible_bounds(&self) -> Option<Rectangle> {
         match self {
             Target::Container { visible_bounds, .. }
@@ -148,6 +152,10 @@ impl Bounded for Target {
     }
 }
 
+/// A selection candidate.
+///
+/// This is provided to [`Selector::select`](crate::Selector::select).
+#[allow(missing_docs)]
 #[derive(Clone)]
 pub enum Candidate<'a> {
     Container {
@@ -190,6 +198,7 @@ pub enum Candidate<'a> {
 }
 
 impl<'a> Candidate<'a> {
+    /// Returns the widget [`Id`] of the [`Candidate`].
     pub fn id(&self) -> Option<&'a Id> {
         match self {
             Candidate::Container { id, .. }
@@ -201,6 +210,7 @@ impl<'a> Candidate<'a> {
         }
     }
 
+    /// Returns the layout bounds of the [`Candidate`].
     pub fn bounds(&self) -> Rectangle {
         match self {
             Candidate::Container { bounds, .. }
@@ -212,6 +222,7 @@ impl<'a> Candidate<'a> {
         }
     }
 
+    /// Returns the visible bounds of the [`Candidate`], in screen coordinates.
     pub fn visible_bounds(&self) -> Option<Rectangle> {
         match self {
             Candidate::Container { visible_bounds, .. }
@@ -224,12 +235,20 @@ impl<'a> Candidate<'a> {
     }
 }
 
+/// A bounded type has both layout bounds and visible bounds.
+///
+/// This trait lets us write generic code over the [`Output`](crate::Selector::Output)
+/// of a [`Selector`](crate::Selector).
 pub trait Bounded: std::fmt::Debug {
+    /// Returns the layout bounds.
     fn bounds(&self) -> Rectangle;
 
+    /// Returns the visible bounds, in screen coordinates.
     fn visible_bounds(&self) -> Option<Rectangle>;
 }
 
+/// A text match.
+#[allow(missing_docs)]
 #[derive(Debug, Clone, PartialEq)]
 pub enum Text {
     Raw {
@@ -245,12 +264,14 @@ pub enum Text {
 }
 
 impl Text {
+    /// Returns the layout bounds of the [`Text`].
     pub fn bounds(&self) -> Rectangle {
         match self {
             Text::Raw { bounds, .. } | Text::Input { bounds, .. } => *bounds,
         }
     }
 
+    /// Returns the visible bounds of the [`Text`], in screen coordinates.
     pub fn visible_bounds(&self) -> Option<Rectangle> {
         match self {
             Text::Raw { visible_bounds, .. }