docs: add examples to helper methods, macros and `Text` doc comments

3 files changed, 130 insertions, 2 deletions

diff --git a/Cargo.toml b/Cargo.toml
index 396241e..aa9bd6d 100644
--- a/Cargo.toml
+++ b/Cargo.toml
@@ -2,7 +2,7 @@
 name = "iced_selection"
 description = "Text selection for `iced`"
 authors = ["pml68 <contact@pml68.dev>"]
-version = "0.0.0"
+version = "0.1.0"
 edition = "2024"
 license = "MIT"
 readme = "README.md"
diff --git a/src/lib.rs b/src/lib.rs
index a3cb57c..3636bc7 100644
--- a/src/lib.rs
+++ b/src/lib.rs
@@ -1,5 +1,6 @@
-//! A text selection API built around `iced`'s [`Paragraph`].
+//! A text selection API built around [`iced`]'s [`Paragraph`].
 //!
+//! [`iced`]: https://iced.rs
 //! [`Paragraph`]: https://docs.iced.rs/iced_graphics/text/paragraph/struct.Paragraph.html
 
 #[cfg(feature = "markdown")]
@@ -15,6 +16,33 @@ pub use markdown::view as markdown;
 pub use text::Text;
 
 /// Creates a new [`Text`] widget with the provided content.
+///
+/// [`Text`]: core::widget::Text
+///
+/// This macro uses the same syntax as [`format!`], but creates a new [`Text`] widget instead.
+///
+/// See [the formatting documentation in `std::fmt`](std::fmt)
+/// for details of the macro argument syntax.
+///
+/// # Examples
+///
+/// ```no_run,ignore
+/// use iced_selection::text;
+///
+/// enum Message {
+///     // ...
+/// }
+///
+/// fn view(_state: &State) -> Element<Message> {
+///     let simple = text!("Hello, world!");
+///
+///     let keyword = text!("Hello, {}", "world!");
+///
+///     let planet = "Earth";
+///     let local_variable = text!("Hello, {planet}!");
+///     // ...
+/// }
+/// ```
 #[macro_export]
 macro_rules! text {
     ($($arg:tt)*) => {
@@ -24,6 +52,29 @@ macro_rules! text {
 
 /// Creates some [`Rich`] text with the given spans.
 ///
+/// # Example
+/// ```no_run,ignore
+/// use iced::font;
+/// use iced_selection::{rich_text, span};
+/// use iced::{color, never, Font};
+///
+/// #[derive(Debug, Clone)]
+/// enum Message {
+///     // ...
+/// }
+///
+/// fn view(state: &State) -> Element<'_, Message> {
+///     rich_text![
+///         span("I am red!").color(color!(0xff0000)),
+///         span(" "),
+///         span("And I am bold!").font(Font { weight: font::Weight::Bold, ..Font::default() }),
+///     ]
+///     .on_link_click(never)
+///     .size(20)
+///     .into()
+/// }
+/// ```
+///
 /// [`Rich`]: crate::text::Rich
 #[macro_export]
 macro_rules! rich_text {
@@ -36,6 +87,21 @@ macro_rules! rich_text {
 }
 
 /// Creates a new [`Text`] widget with the provided content.
+///
+/// # Example
+/// ```no_run,ignore
+/// use iced_selection::text;
+///
+/// enum Message {
+///     // ...
+/// }
+///
+/// fn view(state: &State) -> Element<'_, Message> {
+///     text("Hello, this is iced!")
+///         .size(20)
+///         .into()
+/// }
+/// ```
 pub fn text<'a, Theme, Renderer>(
     text: impl text::IntoFragment<'a>,
 ) -> Text<'a, Theme, Renderer>
@@ -49,6 +115,30 @@ where
 /// Creates some [`Rich`] text with the given spans.
 ///
 /// [`Rich`]: crate::text::Rich
+///
+/// # Example
+/// ```no_run,ignore
+/// use iced::font;
+/// use iced_selection::{rich_text, span};
+/// use iced::{color, never, Font};
+///
+/// #[derive(Debug, Clone)]
+/// enum Message {
+///     LinkClicked(&'static str),
+///     // ...
+/// }
+///
+/// fn view(state: &State) -> Element<'_, Message> {
+///     rich_text([
+///         span("I am red!").color(color!(0xff0000)),
+///         span(" "),
+///         span("And I am bold!").font(Font { weight: font::Weight::Bold, ..Font::default() }),
+///     ])
+///     .on_link_click(never)
+///     .size(20)
+///     .into()
+/// }
+/// ```
 pub fn rich_text<'a, Link, Message, Theme, Renderer>(
     spans: impl AsRef<[text::Span<'a, Link, core::Font>]> + 'a,
 ) -> text::Rich<'a, Link, Message, Theme, Renderer>
@@ -66,6 +156,29 @@ where
 ///
 /// [`Rich`]: crate::text::Rich
 /// [`Span`]: crate::text::Span
+///
+/// # Example
+/// ```no_run,ignore
+/// use iced::font;
+/// use iced_selection::{rich_text, span};
+/// use iced::{color, never, Font};
+///
+/// #[derive(Debug, Clone)]
+/// enum Message {
+///     // ...
+/// }
+///
+/// fn view(state: &State) -> Element<'_, Message> {
+///     rich_text![
+///         span("I am red!").color(color!(0xff0000)),
+///         " ",
+///         span("And I am bold!").font(Font { weight: font::Weight::Bold, ..Font::default() }),
+///     ]
+///     .on_link_click(never)
+///     .size(20)
+///     .into()
+/// }
+/// ```
 pub fn span<'a, Link>(
     text: impl text::IntoFragment<'a>,
 ) -> text::Span<'a, Link, core::Font> {
diff --git a/src/text.rs b/src/text.rs
index cd066c3..ad5c350 100644
--- a/src/text.rs
+++ b/src/text.rs
@@ -43,6 +43,21 @@ use crate::core::{
 use crate::selection::{Selection, SelectionEnd};
 
 /// A bunch of text.
+///
+/// # Example
+/// ```no_run,ignore
+/// use iced_selection::text;
+///
+/// enum Message {
+///     // ...
+/// }
+///
+/// fn view(state: &State) -> Element<'_, Message> {
+///     text("Hello, this is iced!")
+///         .size(20)
+///         .into()
+/// }
+/// ```
 pub struct Text<
     'a,
     Theme = iced_widget::Theme,