From df1e9e0b185a98814b612fc4c1ba8185b06e9355 Mon Sep 17 00:00:00 2001
From: Artyom Sinyugin <writers@altlinux.org>
Date: Wed, 15 Jan 2025 19:28:44 +0300
Subject: [PATCH] xilem: docs update for label, button, sized_box.

---
 xilem/README.md             |  2 +-
 xilem/src/view/button.rs    | 45 +++++++++++++++++++++++++++++++++++++
 xilem/src/view/label.rs     | 23 +++++++++++++++++++
 xilem/src/view/sized_box.rs | 19 ++++++++++++++++
 4 files changed, 88 insertions(+), 1 deletion(-)

diff --git a/xilem/README.md b/xilem/README.md
index d0d85a5ad..2f6129aa0 100644
--- a/xilem/README.md
+++ b/xilem/README.md
@@ -126,7 +126,7 @@ The primitives your [Xilem] app’s view tree will generally be constructed from
 
 ## Minimum supported Rust Version (MSRV)
 
-This version of Xilem has been verified to compile with **Rust 1.81** and later.
+This version of Xilem has been verified to compile with **Rust 1.82** and later.
 
 Future versions of Xilem might increase the Rust version requirement.
 It will not be treated as a breaking change and as such can even happen with small patch releases.
diff --git a/xilem/src/view/button.rs b/xilem/src/view/button.rs
index 171d1949e..b0fc717a9 100644
--- a/xilem/src/view/button.rs
+++ b/xilem/src/view/button.rs
@@ -12,6 +12,48 @@ use crate::{Affine, MessageResult, Pod, ViewCtx, ViewId};
 use super::Transformable;
 
 /// A button which calls `callback` when the primary mouse button (normally left) is pressed.
+///
+/// # Examples
+/// To use button provide it with a button text and a closure.
+/// ```ignore
+/// use xilem::view::button;
+///
+/// struct State {
+///     int: i32,
+/// }
+///
+/// impl State {
+///     fn increase(&mut self) {
+///         self.int += 1;
+///     }
+/// }
+///
+/// button("Button", |state: &mut State| {
+///      state.increase();
+/// })
+/// ```
+///
+/// Create a `button` with a custom `label`.
+///
+/// ```ignore
+/// use xilem::view::{button, label};
+///
+/// struct State {
+///     int: i32,
+/// }
+///
+/// impl State {
+///     fn increase(&mut self) {
+///         self.int += 1;
+///     }
+/// }
+///
+/// let label = label("Button").weight(FontWeight::BOLD);
+///
+/// button(label, |state: &mut State| {
+///     state.increase();
+/// })
+/// ```
 pub fn button<State, Action>(
     label: impl Into<Label>,
     callback: impl Fn(&mut State) -> Action + Send + 'static,
@@ -40,6 +82,9 @@ pub fn button_any_pointer<State, Action>(
     }
 }
 
+/// The [`View`] created by [`button`].
+///
+/// See `button` documentation for more context.
 #[must_use = "View values do nothing unless provided to Xilem."]
 pub struct Button<F> {
     label: Label,
diff --git a/xilem/src/view/label.rs b/xilem/src/view/label.rs
index 1c387497b..2bf2325a3 100644
--- a/xilem/src/view/label.rs
+++ b/xilem/src/view/label.rs
@@ -11,6 +11,22 @@ use crate::{Affine, Color, MessageResult, Pod, TextAlignment, View, ViewCtx, Vie
 
 use super::Transformable;
 
+/// A non-interactive text element.
+/// # Example
+///
+/// ```ignore
+/// use xilem::palette;
+/// use xilem::view::label;
+/// use masonry::TextAlignment;
+/// use masonry::parley::fontique;
+///
+/// label("Text example.")
+///     .brush(palette::css::RED)
+///     .alignment(TextAlignment::Middle)
+///     .text_size(24.0)
+///     .weight(FontWeight::BOLD)
+///     .with_font(fontique::GenericFamily::Serif)
+/// ```
 pub fn label(label: impl Into<ArcStr>) -> Label {
     Label {
         label: label.into(),
@@ -23,6 +39,9 @@ pub fn label(label: impl Into<ArcStr>) -> Label {
     }
 }
 
+/// The [`View`] created by [`label`].
+///
+/// See `label` documentation for more context.
 #[must_use = "View values do nothing unless provided to Xilem."]
 pub struct Label {
     // Public for button and variable_label as a semi-interim state.
@@ -36,23 +55,27 @@ pub struct Label {
 }
 
 impl Label {
+    /// In most cases brush sets text color, but gradients and images are also supported.
     #[doc(alias = "color")]
     pub fn brush(mut self, brush: impl Into<Brush>) -> Self {
         self.text_brush = brush.into();
         self
     }
 
+    /// Sets text alignment: `Start`, `Middle`, `End` or `Justified`.
     pub fn alignment(mut self, alignment: TextAlignment) -> Self {
         self.alignment = alignment;
         self
     }
 
+    /// Sets text size.
     #[doc(alias = "font_size")]
     pub fn text_size(mut self, text_size: f32) -> Self {
         self.text_size = text_size;
         self
     }
 
+    /// Sets font weight.
     pub fn weight(mut self, weight: FontWeight) -> Self {
         self.weight = weight;
         self
diff --git a/xilem/src/view/sized_box.rs b/xilem/src/view/sized_box.rs
index 6020e7a3e..d6c0b31ad 100644
--- a/xilem/src/view/sized_box.rs
+++ b/xilem/src/view/sized_box.rs
@@ -18,6 +18,22 @@ use super::Transformable;
 /// This widget forces its child to have a specific width and/or height (assuming values are permitted by
 /// this widget's parent). If either the width or height is not set, this widget will size itself
 /// to match the child's size in that dimension.
+///
+/// # Example
+/// See more methods for `sized_box` on [`SizedBox`] page.
+/// ```ignore
+/// use xilem::view::{sized_box, button};
+/// use xilem::palette;
+/// use vello::kurbo::RoundedRectRadii;
+/// use masonry::widget::Padding;
+///
+/// sized_box(button("Button", |data: &mut i32| *data+=1))
+///     .expand()
+///     .background(palette::css::RED)
+///     .border(palette::css::YELLOW, 20.)
+///     .rounded(RoundedRectRadii::from_single_radius(5.))
+///     .padding(Padding::from(5.))
+/// ```
 pub fn sized_box<State, Action, V>(inner: V) -> SizedBox<V, State, Action>
 where
     V: WidgetView<State, Action>,
@@ -35,6 +51,9 @@ where
     }
 }
 
+/// The [`View`] created by [`sized_box`].
+///
+/// See `sized_box` documentation for more context.
 #[must_use = "View values do nothing unless provided to Xilem."]
 pub struct SizedBox<V, State, Action = ()> {
     inner: V,