Show `container` doc example in multiple places

3 files changed, 65 insertions, 11 deletions

diff --git a/widget/src/canvas.rs b/widget/src/canvas.rs
index bb6b0353..9fbccf82 100644
--- a/widget/src/canvas.rs
+++ b/widget/src/canvas.rs
@@ -1,8 +1,6 @@
-//! Draw 2D graphics for your users.
+//! Canvases can be leveraged to draw interactive 2D graphics.
 //!
 //! # Example: Drawing a Simple Circle
-//! Here's how we can use a [`Canvas`] to draw a simple circle:
-//!
 //! ```no_run
 //! # mod iced { pub mod widget { pub use iced_widget::*; } pub use iced_widget::Renderer; pub use iced_widget::core::*; }
 //! # pub type State = ();
@@ -91,8 +89,6 @@ pub type Frame<Renderer = crate::Renderer> = geometry::Frame<Renderer>;
 /// A widget capable of drawing 2D graphics.
 ///
 /// # Example: Drawing a Simple Circle
-/// Here's how we can use a [`Canvas`] to draw a simple circle:
-///
 /// ```no_run
 /// # mod iced { pub mod widget { pub use iced_widget::*; } pub use iced_widget::Renderer; pub use iced_widget::core::*; }
 /// # pub type State = ();
diff --git a/widget/src/container.rs b/widget/src/container.rs
index 3b794099..b256540c 100644
--- a/widget/src/container.rs
+++ b/widget/src/container.rs
@@ -1,4 +1,24 @@
-//! Decorate content and apply alignment.
+//! Containers let you align a widget inside their boundaries.
+//!
+//! # 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::container;
+//!
+//! enum Message {
+//!     // ...
+//! }
+//!
+//! fn view(state: &State) -> Element<'_, Message> {
+//!     container("This text is centered inside a rounded box!")
+//!         .padding(10)
+//!         .center(800)
+//!         .style(container::rounded_box)
+//!         .into()
+//! }
+//! ```
 use crate::core::alignment::{self, Alignment};
 use crate::core::border::{self, Border};
 use crate::core::event::{self, Event};
@@ -16,9 +36,27 @@ use crate::core::{
 };
 use crate::runtime::task::{self, Task};
 
-/// An element decorating some content.
+/// A widget that aligns its contents inside of its boundaries.
 ///
-/// It is normally used for alignment purposes.
+/// # 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::container;
+///
+/// enum Message {
+///     // ...
+/// }
+///
+/// fn view(state: &State) -> Element<'_, Message> {
+///     container("This text is centered inside a rounded box!")
+///         .padding(10)
+///         .center(800)
+///         .style(container::rounded_box)
+///         .into()
+/// }
+/// ```
 #[allow(missing_debug_implementations)]
 pub struct Container<
     'a,
diff --git a/widget/src/helpers.rs b/widget/src/helpers.rs
index d839bc3a..0699446d 100644
--- a/widget/src/helpers.rs
+++ b/widget/src/helpers.rs
@@ -128,7 +128,27 @@ macro_rules! rich_text {
 
 /// Creates a new [`Container`] with the provided content.
 ///
-/// [`Container`]: crate::Container
+/// Containers let you align a widget inside their boundaries.
+///
+/// # 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::container;
+///
+/// enum Message {
+///     // ...
+/// }
+///
+/// fn view(state: &State) -> Element<'_, Message> {
+///     container("This text is centered inside a rounded box!")
+///         .padding(10)
+///         .center(800)
+///         .style(container::rounded_box)
+///         .into()
+/// }
+/// ```
 pub fn container<'a, Message, Theme, Renderer>(
     content: impl Into<Element<'a, Message, Theme, Renderer>>,
 ) -> Container<'a, Message, Theme, Renderer>
@@ -1084,11 +1104,11 @@ where
 
 /// Creates a new [`Canvas`].
 ///
+/// Canvases can be leveraged to draw interactive 2D graphics.
+///
 /// [`Canvas`]: crate::Canvas
 ///
 /// # Example: Drawing a Simple Circle
-/// Here's how we can use a [`Canvas`] to draw a simple circle:
-///
 /// ```no_run
 /// # mod iced { pub mod widget { pub use iced_widget::*; } pub use iced_widget::Renderer; pub use iced_widget::core::*; }
 /// # pub type State = ();