Merge pull request #2587 from iced-rs/improve-api-reference

Add widget examples to API reference and update `README`

3 files changed, 138 insertions, 14 deletions

diff --git a/widget/src/text.rs b/widget/src/text.rs
index 9bf7fce4..c2243434 100644
--- a/widget/src/text.rs
+++ b/widget/src/text.rs
@@ -5,6 +5,26 @@ pub use crate::core::text::{Fragment, Highlighter, IntoFragment, Span};
 pub use crate::core::widget::text::*;
 pub use rich::Rich;
 
-/// A paragraph.
+/// A bunch of text.
+///
+/// # Example
+/// ```no_run
+/// # mod iced { pub mod widget { pub use iced_widget::*; } pub use iced_widget::Renderer; pub use iced_widget::core::*; }
+/// # pub type State = ();
+/// # pub type Element<'a, Message> = iced_widget::core::Element<'a, Message, iced_widget::Theme, iced_widget::Renderer>;
+/// use iced::widget::text;
+/// use iced::color;
+///
+/// enum Message {
+///     // ...
+/// }
+///
+/// fn view(state: &State) -> Element<'_, Message> {
+///     text("Hello, this is iced!")
+///         .size(20)
+///         .color(color!(0x0000ff))
+///         .into()
+/// }
+/// ```
 pub type Text<'a, Theme = crate::Theme, Renderer = crate::Renderer> =
     crate::core::widget::Text<'a, Theme, Renderer>;
diff --git a/widget/src/text_editor.rs b/widget/src/text_editor.rs
index 1df97962..59795318 100644
--- a/widget/src/text_editor.rs
+++ b/widget/src/text_editor.rs
@@ -1,4 +1,36 @@
-//! Display a multi-line text input for text editing.
+//! Text editors display a multi-line text input for text editing.
+//!
+//! # Example
+//! ```no_run
+//! # mod iced { pub mod widget { pub use iced_widget::*; } pub use iced_widget::Renderer; pub use iced_widget::core::*; }
+//! # pub type Element<'a, Message> = iced_widget::core::Element<'a, Message, iced_widget::Theme, iced_widget::Renderer>;
+//! #
+//! use iced::widget::text_editor;
+//!
+//! struct State {
+//!    content: text_editor::Content,
+//! }
+//!
+//! #[derive(Debug, Clone)]
+//! enum Message {
+//!     Edit(text_editor::Action)
+//! }
+//!
+//! fn view(state: &State) -> Element<'_, Message> {
+//!     text_editor(&state.content)
+//!         .placeholder("Type something here...")
+//!         .on_action(Message::Edit)
+//!         .into()
+//! }
+//!
+//! fn update(state: &mut State, message: Message) {
+//!     match message {
+//!         Message::Edit(action) => {
+//!             state.content.perform(action);
+//!         }
+//!     }
+//! }
+//! ```
 use crate::core::alignment;
 use crate::core::clipboard::{self, Clipboard};
 use crate::core::event::{self, Event};
@@ -27,6 +59,38 @@ use std::sync::Arc;
 pub use text::editor::{Action, Edit, Motion};
 
 /// A multi-line text input.
+///
+/// # Example
+/// ```no_run
+/// # mod iced { pub mod widget { pub use iced_widget::*; } pub use iced_widget::Renderer; pub use iced_widget::core::*; }
+/// # pub type Element<'a, Message> = iced_widget::core::Element<'a, Message, iced_widget::Theme, iced_widget::Renderer>;
+/// #
+/// use iced::widget::text_editor;
+///
+/// struct State {
+///    content: text_editor::Content,
+/// }
+///
+/// #[derive(Debug, Clone)]
+/// enum Message {
+///     Edit(text_editor::Action)
+/// }
+///
+/// fn view(state: &State) -> Element<'_, Message> {
+///     text_editor(&state.content)
+///         .placeholder("Type something here...")
+///         .on_action(Message::Edit)
+///         .into()
+/// }
+///
+/// fn update(state: &mut State, message: Message) {
+///     match message {
+///         Message::Edit(action) => {
+///             state.content.perform(action);
+///         }
+///     }
+/// }
+/// ```
 #[allow(missing_debug_implementations)]
 pub struct TextEditor<
     'a,
diff --git a/widget/src/text_input.rs b/widget/src/text_input.rs
index 3032dd13..5bbf76f5 100644
--- a/widget/src/text_input.rs
+++ b/widget/src/text_input.rs
@@ -1,6 +1,35 @@
-//! Display fields that can be filled with text.
+//! Text inputs display fields that can be filled with text.
 //!
-//! A [`TextInput`] has some local [`State`].
+//! # Example
+//! ```no_run
+//! # mod iced { pub mod widget { pub use iced_widget::*; } pub use iced_widget::Renderer; pub use iced_widget::core::*; }
+//! # pub type Element<'a, Message> = iced_widget::core::Element<'a, Message, iced_widget::Theme, iced_widget::Renderer>;
+//! #
+//! use iced::widget::text_input;
+//!
+//! struct State {
+//!    content: String,
+//! }
+//!
+//! #[derive(Debug, Clone)]
+//! enum Message {
+//!     ContentChanged(String)
+//! }
+//!
+//! fn view(state: &State) -> Element<'_, Message> {
+//!     text_input("Type something here...", &state.content)
+//!         .on_input(Message::ContentChanged)
+//!         .into()
+//! }
+//!
+//! fn update(state: &mut State, message: Message) {
+//!     match message {
+//!         Message::ContentChanged(content) => {
+//!             state.content = content;
+//!         }
+//!     }
+//! }
+//! ```
 mod editor;
 mod value;
 
@@ -38,23 +67,34 @@ use crate::runtime::Action;
 ///
 /// # Example
 /// ```no_run
-/// # pub type TextInput<'a, Message> = iced_widget::TextInput<'a, Message>;
+/// # mod iced { pub mod widget { pub use iced_widget::*; } pub use iced_widget::Renderer; pub use iced_widget::core::*; }
+/// # pub type Element<'a, Message> = iced_widget::core::Element<'a, Message, iced_widget::Theme, iced_widget::Renderer>;
 /// #
+/// use iced::widget::text_input;
+///
+/// struct State {
+///    content: String,
+/// }
+///
 /// #[derive(Debug, Clone)]
 /// enum Message {
-///     TextInputChanged(String),
+///     ContentChanged(String)
 /// }
 ///
-/// let value = "Some text";
+/// fn view(state: &State) -> Element<'_, Message> {
+///     text_input("Type something here...", &state.content)
+///         .on_input(Message::ContentChanged)
+///         .into()
+/// }
 ///
-/// let input = TextInput::new(
-///     "This is the placeholder...",
-///     value,
-/// )
-/// .on_input(Message::TextInputChanged)
-/// .padding(10);
+/// fn update(state: &mut State, message: Message) {
+///     match message {
+///         Message::ContentChanged(content) => {
+///             state.content = content;
+///         }
+///     }
+/// }
 /// ```
-/// ![Text input drawn by `iced_wgpu`](https://github.com/iced-rs/iced/blob/7760618fb112074bc40b148944521f312152012a/docs/images/text_input.png?raw=true)
 #[allow(missing_debug_implementations)]
 pub struct TextInput<
     'a,