More docs review.

TODO/_current.md

@@ -8,7 +8,7 @@
     - Review badges.
 * Review docs.
     - Do a full read, look for typos or failed links.
-        - Last reviewed `zero_ui::clipboard`.
+        - Last reviewed `zero_ui::color`.
 
 # Publish
 

zero-ui-color/src/filter.rs

@@ -17,9 +17,6 @@ use crate::{RenderColor, Rgba};
 
 /// A color filter or combination of filters.
 ///
-/// You can start a filter from one of the standalone filter functions, and then combine more filters using
-/// the builder call style.
-///
 /// # Examples
 ///
 /// ```
@@ -35,65 +32,8 @@ pub struct Filter {
     filters: Vec<FilterData>,
     needs_layout: bool,
 }
+
 impl Filter {
-    fn op(mut self, op: FilterOp) -> Self {
-        self.filters.push(FilterData::Op(op));
-        self
-    }
-
-    /// Compute a [`RenderFilter`] in the current [`LAYOUT`] context.
-    ///
-    /// Most filters convert one-to-one, effects that have a [`Length`] value use the
-    /// layout context to calculate relative values.
-    ///
-    /// Relative blur radius lengths are calculated using the `constraints().fill_size().width` value.
-    ///
-    /// [`LAYOUT`]: zero_ui_layout::context::LAYOUT
-    pub fn layout(&self) -> RenderFilter {
-        self.filters
-            .iter()
-            .map(|f| match f {
-                FilterData::Op(op) => *op,
-                FilterData::Blur(l) => {
-                    let l = l.layout_f32_x();
-                    FilterOp::Blur(l, l)
-                }
-                FilterData::DropShadow {
-                    offset,
-                    blur_radius,
-                    color,
-                } => FilterOp::DropShadow(Shadow {
-                    offset: offset.layout().to_wr().to_vector(),
-                    color: RenderColor::from(*color),
-                    blur_radius: blur_radius.layout_f32_x(),
-                }),
-            })
-            .collect()
-    }
-
-    /// Compute a [`RenderFilter`] if the filter is not affected by layout.
-    pub fn try_render(&self) -> Option<RenderFilter> {
-        if self.needs_layout {
-            return None;
-        }
-
-        let mut r = Vec::with_capacity(self.filters.len());
-
-        for f in &self.filters {
-            match f {
-                FilterData::Op(op) => r.push(*op),
-                FilterData::Blur(_) | FilterData::DropShadow { .. } => unreachable!(),
-            }
-        }
-
-        Some(r)
-    }
-
-    /// Returns `true` if this filter is affected by the layout context where it is evaluated.
-    pub fn needs_layout(&self) -> bool {
-        self.needs_layout
-    }
-
     /// Add an opacity adjustment to the filter, zero is fully transparent, one is the input transparency.
     pub fn opacity<A: Into<Factor>>(self, alpha: A) -> Self {
         let alpha_value = alpha.into().0;
@@ -171,6 +111,14 @@ impl Filter {
 }
 
 impl Filter {
+    /// New default empty.
+    pub const fn new() -> Filter {
+        Self {
+            filters: vec![],
+            needs_layout: false,
+        }
+    }
+
     /// New [`Filter::opacity`].
     pub fn new_opacity<A: Into<Factor>>(alpha: A) -> Filter {
         Filter::default().opacity(alpha)
@@ -221,6 +169,66 @@ impl Filter {
     }
 }
 
+impl Filter {
+    fn op(mut self, op: FilterOp) -> Self {
+        self.filters.push(FilterData::Op(op));
+        self
+    }
+
+    /// Compute a [`RenderFilter`] in the current [`LAYOUT`] context.
+    ///
+    /// Most filters convert one-to-one, effects that have a [`Length`] value use the
+    /// layout context to calculate relative values.
+    ///
+    /// Relative blur radius lengths are calculated using the `constraints().fill_size().width` value.
+    ///
+    /// [`LAYOUT`]: zero_ui_layout::context::LAYOUT
+    pub fn layout(&self) -> RenderFilter {
+        self.filters
+            .iter()
+            .map(|f| match f {
+                FilterData::Op(op) => *op,
+                FilterData::Blur(l) => {
+                    let l = l.layout_f32_x();
+                    FilterOp::Blur(l, l)
+                }
+                FilterData::DropShadow {
+                    offset,
+                    blur_radius,
+                    color,
+                } => FilterOp::DropShadow(Shadow {
+                    offset: offset.layout().to_wr().to_vector(),
+                    color: RenderColor::from(*color),
+                    blur_radius: blur_radius.layout_f32_x(),
+                }),
+            })
+            .collect()
+    }
+
+    /// Compute a [`RenderFilter`] if the filter is not affected by layout.
+    pub fn try_render(&self) -> Option<RenderFilter> {
+        if self.needs_layout {
+            return None;
+        }
+
+        let mut r = Vec::with_capacity(self.filters.len());
+
+        for f in &self.filters {
+            match f {
+                FilterData::Op(op) => r.push(*op),
+                FilterData::Blur(_) | FilterData::DropShadow { .. } => unreachable!(),
+            }
+        }
+
+        Some(r)
+    }
+
+    /// Returns `true` if this filter is affected by the layout context where it is evaluated.
+    pub fn needs_layout(&self) -> bool {
+        self.needs_layout
+    }
+}
+
 impl fmt::Debug for Filter {
     fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
         if f.alternate() {

zero-ui-color/src/gradient.rs

@@ -8,9 +8,12 @@ use zero_ui_view_api::unit::*;
 use crate::*;
 
 /// Specifies how to draw the gradient outside the first and last stop.
-#[derive(Clone, Copy, PartialEq, Eq, serde::Serialize, serde::Deserialize)]
+#[derive(Clone, Default, Copy, PartialEq, Eq, serde::Serialize, serde::Deserialize)]
 pub enum ExtendMode {
-    /// Default value. The color values at the ends of the gradient vector fill the remaining space.
+    /// The color values at the ends of the gradient vector fill the remaining space.
+    ///
+    /// This is the default mode.
+    #[default]
     Clamp,
     /// The gradient is repeated until the space is filled.
     Repeat,
@@ -441,7 +444,7 @@ impl ColorStop {
     ///
     /// A [`Length::Default`] offset indicates that the color stop is positional.
     ///
-    /// # Resolution
+    /// # Layout
     ///
     /// When a [`GradientStops`] calculates layout, positional stops are resolved like this:
     ///

zero-ui-color/src/lib.rs

@@ -1313,7 +1313,7 @@ impl ColorPair {
     }
 }
 
-/// Defines the color space for color interpolation in a context.
+/// Defines the color space for color interpolation.
 ///
 /// See [`with_lerp_space`] for more details.
 #[derive(Default, Debug, Clone, Copy, PartialEq, Eq, serde::Serialize, serde::Deserialize)]
@@ -1331,6 +1331,9 @@ pub enum LerpSpace {
 }
 
 /// Gets the lerp space used for color interpolation.
+///
+/// Must be called only inside the [`with_lerp_space`] closure or in the lerp implementation of a variable animating
+/// with [`rgba_sampler`] or [`hsla_linear_sampler`].
 pub fn lerp_space() -> LerpSpace {
     LERP_SPACE.get_clone()
 }

zero-ui-color/src/mix.rs

@@ -52,7 +52,7 @@ macro_rules! impl_mix {
 
             $(
                 paste! {
-                    #[doc = "Mix `background` over `self` using the [`MixBlendMode::`" $Mode "`]."]
+                    #[doc = "Mix `background` over `self` using the [`MixBlendMode::" $Mode "`]."]
                     ///
                     $(#[$meta])*
                     pub fn [<mix_ $Mode:lower>](self, background: PreMulRgba) -> PreMulRgba {
@@ -104,7 +104,7 @@ macro_rules! impl_mix {
                     ///
                     $(#[$meta])*
                     ///
-                    /// This method converts both [`PreMulRgba`] and the result back to `Rgba`.
+                    /// This method converts both inputs to [`PreMulRgba`] and the result back to `Rgba`.
                     pub fn [<mix_ $Mode:lower>](self, background: Rgba) -> Rgba {
                         self.pre_mul().[<mix_ $Mode:lower>](background.pre_mul()).to_rgba()
                     }
@@ -116,7 +116,7 @@ macro_rules! impl_mix {
                     ///
                     $(#[$ns_meta])*
                     ///
-                    /// This method converts both [`Hsla`] and the result back to `Rgba`.
+                    /// This method converts both inputs to [`Hsla`] and the result back to `Rgba`.
                     pub fn [<mix_ $NsMode:lower>](self, background: Rgba) -> Rgba {
                         self.to_hsla().[<mix_ $NsMode:lower>](background.to_hsla()).to_rgba()
                     }

zero-ui-view-api/src/config.rs

@@ -154,10 +154,10 @@ impl fmt::Debug for FontAntiAliasing {
 /// Color scheme preference.
 #[derive(Clone, Copy, Debug, PartialEq, Eq, Serialize, Deserialize)]
 pub enum ColorScheme {
-    /// Dark foreground, light background.
+    /// Dark text, light background.
     Light,
 
-    /// Light foreground, dark background.
+    /// Light text, dark background.
     Dark,
 }
 impl Default for ColorScheme {

zero-ui-wgt-fill/src/node.rs

@@ -114,9 +114,9 @@ where
 /// Linear gradient.
 ///
 /// Can be used as a node that fills the available space with the gradient, or can continue building a linear
-/// gradient.
+/// or tiled linear gradient.
 ///
-/// Use [`gradient`] or [`linear_gradient`] to build.
+/// Use [`gradient`] or [`linear_gradient`] to start building.
 ///
 /// [`gradient`]: fn@gradient
 pub struct LinearGradient<S, A, E> {
@@ -187,12 +187,9 @@ where
 /// Tiled linear gradient.
 ///
 /// Can be used as a node that fills the available space with the gradient tiles, or can continue building a
-/// repeating linear gradient.
+/// tiled linear gradient.
 ///
-///
-/// Use [`gradient`], [`linear_gradient`] to build.
-///
-/// [`gradient`]: fn@gradient
+/// Use [`LinearGradient::tile`] to build.
 pub struct TiledLinearGradient<S, A, E, O, T, TS> {
     stops: S,
     axis: A,
@@ -260,10 +257,10 @@ where
 
 /// Radial gradient.
 ///
-/// Can be used as a node that fills the available space with the gradient, or can continue building a linear
-/// gradient.
+/// Can be used as a node that fills the available space with the gradient, or can continue building a radial
+/// or tiled radial gradient.
 ///
-/// Use [`gradient`] or [`radial_gradient`] to build.
+/// Use [`gradient`] or [`radial_gradient`] to start building.
 ///  
 /// [`gradient`]: fn@gradient
 pub struct RadialGradient<S, C, R, E> {
@@ -336,8 +333,7 @@ where
 ///
 /// Can be used as a node that fills the available space with the gradient tiles, or can continue building the gradient.
 ///
-///
-/// Use [`gradient`], [`radial_gradient`] to build.
+/// Use [`RadialGradient::tile`] to build.
 ///  
 /// [`gradient`]: fn@gradient
 pub struct TiledRadialGradient<S, C, R, E, O, T, TS> {
@@ -411,10 +407,10 @@ where
 
 /// Conic gradient.
 ///
-/// Can be used as a node that fills the available space with the gradient, or can continue building a linear
-/// gradient.
+/// Can be used as a node that fills the available space with the gradient, or can continue building the conic
+/// or a tiled conic gradient.
 ///
-/// Use [`gradient`] or [`conic_gradient`] to build.
+/// Use [`gradient`] or [`conic_gradient`] to start building.
 ///  
 /// [`gradient`]: fn@gradient
 pub struct ConicGradient<S, C, A, E> {
@@ -487,7 +483,7 @@ where
 ///
 /// Can be used as a node that fills the available space with the gradient tiles, or can continue building the gradient.
 ///
-/// Use [`gradient`], [`conic_gradient`] to build.
+/// Use [`ConicGradient::tile`] to build.
 ///  
 /// [`gradient`]: fn@gradient
 pub struct TiledConicGradient<S, C, A, E, O, T, TS> {

zero-ui/src/color.rs

@@ -114,7 +114,7 @@ pub use zero_ui_wgt::color_scheme;
 
 pub use zero_ui_wgt_fill::node::flood;
 
-/// Color filters.
+/// Color filter types and properties.
 pub mod filter {
     pub use zero_ui_color::filter::{ColorMatrix, Filter, RenderFilter};
 
@@ -126,7 +126,7 @@ pub mod filter {
     };
 }
 
-/// Color gradient.
+/// Color gradient types and nodes.
 pub mod gradient {
     pub use zero_ui_color::gradient::{
         stops, ColorStop, ExtendMode, GradientRadius, GradientRadiusBase, GradientStop, GradientStops, LinearGradientAxis,