Show `keyed_column` doc example in multiple places

3 files changed, 68 insertions, 8 deletions

diff --git a/widget/src/helpers.rs b/widget/src/helpers.rs
index bae2e10e..11eed6ba 100644
--- a/widget/src/helpers.rs
+++ b/widget/src/helpers.rs
@@ -191,7 +191,27 @@ where
     Column::with_children(children)
 }
 
-/// Creates a new [`keyed::Column`] with the given children.
+/// Creates a new [`keyed::Column`] from an iterator of elements.
+///
+/// Keyed columns distribute content vertically while keeping continuity.
+///
+/// # Example
+/// ```no_run
+/// # mod iced { pub mod widget { pub use iced_widget::*; } }
+/// # pub type State = ();
+/// # pub type Element<'a, Message> = iced_widget::core::Element<'a, Message, iced_widget::Theme, iced_widget::Renderer>;
+/// use iced::widget::{keyed_column, text};
+///
+/// enum Message {
+///     // ...
+/// }
+///
+/// fn view(state: &State) -> Element<'_, Message> {
+///     keyed_column((0..=100).map(|i| {
+///         (i, text!("Item {i}").into())
+///     })).into()
+/// }
+/// ```
 pub fn keyed_column<'a, Key, Message, Theme, Renderer>(
     children: impl IntoIterator<Item = (Key, Element<'a, Message, Theme, Renderer>)>,
 ) -> keyed::Column<'a, Key, Message, Theme, Renderer>
diff --git a/widget/src/keyed.rs b/widget/src/keyed.rs
index ad531e66..923cb118 100644
--- a/widget/src/keyed.rs
+++ b/widget/src/keyed.rs
@@ -1,4 +1,4 @@
-//! Use widgets that can provide hints to ensure continuity.
+//! Keyed widgets can provide hints to ensure continuity.
 //!
 //! # What is continuity?
 //! Continuity is the feeling of persistence of state.
@@ -41,13 +41,35 @@ pub mod column;
 
 pub use column::Column;
 
-/// Creates a [`Column`] with the given children.
+/// Creates a keyed [`Column`] with the given children.
+///
+/// Keyed columns distribute content vertically while keeping continuity.
+///
+/// # Example
+/// ```no_run
+/// # mod iced { pub mod widget { pub use iced_widget::*; } }
+/// # pub type State = ();
+/// # pub type Element<'a, Message> = iced_widget::core::Element<'a, Message, iced_widget::Theme, iced_widget::Renderer>;
+/// use iced::widget::keyed_column;
+///
+/// enum Message {
+///     // ...
+/// }
+///
+/// fn view(state: &State) -> Element<'_, Message> {
+///     keyed_column![
+///         (0, "Item 0"),
+///         (1, "Item 1"),
+///         (2, "Item 2"),
+///     ].into()
+/// }
+/// ```
 #[macro_export]
 macro_rules! keyed_column {
     () => (
-        $crate::Column::new()
+        $crate::keyed::Column::new()
     );
-    ($($x:expr),+ $(,)?) => (
-        $crate::keyed::Column::with_children(vec![$($crate::core::Element::from($x)),+])
+    ($(($key:expr, $x:expr)),+ $(,)?) => (
+        $crate::keyed::Column::with_children(vec![$(($key, $crate::core::Element::from($x))),+])
     );
 }
diff --git a/widget/src/keyed/column.rs b/widget/src/keyed/column.rs
index 2c56c605..5852ede1 100644
--- a/widget/src/keyed/column.rs
+++ b/widget/src/keyed/column.rs
@@ -1,4 +1,4 @@
-//! Distribute content vertically.
+//! Keyed columns distribute content vertically while keeping continuity.
 use crate::core::event::{self, Event};
 use crate::core::layout;
 use crate::core::mouse;
@@ -11,7 +11,25 @@ use crate::core::{
     Shell, Size, Vector, Widget,
 };
 
-/// A container that distributes its contents vertically.
+/// A container that distributes its contents vertically while keeping continuity.
+///
+/// # Example
+/// ```no_run
+/// # mod iced { pub mod widget { pub use iced_widget::*; } }
+/// # pub type State = ();
+/// # pub type Element<'a, Message> = iced_widget::core::Element<'a, Message, iced_widget::Theme, iced_widget::Renderer>;
+/// use iced::widget::{keyed_column, text};
+///
+/// enum Message {
+///     // ...
+/// }
+///
+/// fn view(state: &State) -> Element<'_, Message> {
+///     keyed_column((0..=100).map(|i| {
+///         (i, text!("Item {i}").into())
+///     })).into()
+/// }
+/// ```
 #[allow(missing_debug_implementations)]
 pub struct Column<
     'a,