Improve docs for `Sandbox` and `Application`

author: Héctor Ramón Jiménez <hector0193@gmail.com> 2020-04-01 04:35:24 +0200
committer: Héctor Ramón Jiménez <hector0193@gmail.com> 2020-04-02 03:44:14 +0200
commit: f5e7e0625eec96f96d9dcbe514198a82bd5a49ec (patch)
tree: ee358df2558c8122498061eac3e9bf509df7e204 /src
parent: 4c44517556976454c0598c876addb10b88515cda (diff)
download: iced-f5e7e0625eec96f96d9dcbe514198a82bd5a49ec.tar.gz
iced-f5e7e0625eec96f96d9dcbe514198a82bd5a49ec.tar.bz2
iced-f5e7e0625eec96f96d9dcbe514198a82bd5a49ec.zip
5 files changed, 122 insertions, 107 deletions
diff --git a/src/application.rs b/src/application.rs
index 43aa57a3..8c4a77a2 100644
--- a/src/application.rs
+++ b/src/application.rs
@@ -9,75 +9,76 @@ use crate::{window, Command, Element, Executor, Settings, Subscription};
 /// - On the web, it will take control of the `<title>` and the `<body>` of the
 ///   document.
 ///
-/// An [`Application`](trait.Application.html) can execute asynchronous actions
-/// by returning a [`Command`](struct.Command.html) in some of its methods. If
+/// An [`Application`] can execute asynchronous actions by returning a
+/// [`Command`](struct.Command.html) in some of its methods. If
 /// you do not intend to perform any background work in your program, the
 /// [`Sandbox`](trait.Sandbox.html) trait offers a simplified interface.
 ///
-/// # Example
-/// Let's say we want to run the [`Counter` example we implemented
-/// before](index.html#overview). We just need to fill in the gaps:
+/// [`Application`]: trait.Application.html
+///
+/// # Examples
+/// [The repository has a bunch of examples] that use the [`Application`] trait:
+///
+/// - [`clock`], an application that uses the [`Canvas`] widget to draw a clock
+/// and its hands to display the current time.
+/// - [`download_progress`], a basic application that asynchronously downloads
+/// a dummy file of 100 MB and tracks the download progress.
+/// - [`events`], a log of native events displayed using a conditional
+/// [`Subscription`].
+/// - [`pokedex`], an application that displays a random Pokédex entry (sprite
+/// included!) by using the [PokéAPI].
+/// - [`solar_system`], an animated solar system drawn using the [`Canvas`] widget
+/// and showcasing how to compose different transforms.
+/// - [`stopwatch`], a watch with start/stop and reset buttons showcasing how
+/// to listen to time.
+/// - [`todos`], a todos tracker inspired by [TodoMVC].
+///
+/// [The repository has a bunch of examples]: https://github.com/hecrj/iced/tree/0.1/examples
+/// [`clock`]: https://github.com/hecrj/iced/tree/0.1/examples/clock
+/// [`download_progress`]: https://github.com/hecrj/iced/tree/0.1/examples/download_progress
+/// [`events`]: https://github.com/hecrj/iced/tree/0.1/examples/events
+/// [`pokedex`]: https://github.com/hecrj/iced/tree/0.1/examples/pokedex
+/// [`solar_system`]: https://github.com/hecrj/iced/tree/0.1/examples/solar_system
+/// [`stopwatch`]: https://github.com/hecrj/iced/tree/0.1/examples/stopwatch
+/// [`todos`]: https://github.com/hecrj/iced/tree/0.1/examples/todos
+/// [`Canvas`]: widget/canvas/struct.Canvas.html
+/// [PokéAPI]: https://pokeapi.co/
+/// [`Subscription`]: type.Subscription.html
+/// [TodoMVC]: http://todomvc.com/
+///
+/// ## A simple "Hello, world!"
+///
+/// If you just want to get started, here is a simple [`Application`] that
+/// says "Hello, world!":
 ///
 /// ```no_run
-/// use iced::{button, executor, Application, Button, Column, Command, Element, Settings, Text};
+/// use iced::{executor, Application, Command, Element, Settings, Text};
 ///
 /// pub fn main() {
-///     Counter::run(Settings::default())
+///     Hello::run(Settings::default())
 /// }
 ///
-/// #[derive(Default)]
-/// struct Counter {
-///     value: i32,
-///     increment_button: button::State,
-///     decrement_button: button::State,
-/// }
-///
-/// #[derive(Debug, Clone, Copy)]
-/// enum Message {
-///     IncrementPressed,
-///     DecrementPressed,
-/// }
+/// struct Hello;
 ///
-/// impl Application for Counter {
+/// impl Application for Hello {
 ///     type Executor = executor::Null;
-///     type Message = Message;
+///     type Message = ();
 ///     type Flags = ();
 ///
-///     fn new(_flags: ()) -> (Self, Command<Message>) {
-///         (Self::default(), Command::none())
+///     fn new(_flags: ()) -> (Hello, Command<Self::Message>) {
+///         (Hello, Command::none())
 ///     }
 ///
 ///     fn title(&self) -> String {
-///         String::from("A simple counter")
+///         String::from("A cool application")
 ///     }
 ///
-///     fn update(&mut self, message: Message) -> Command<Message> {
-///         match message {
-///             Message::IncrementPressed => {
-///                 self.value += 1;
-///             }
-///             Message::DecrementPressed => {
-///                 self.value -= 1;
-///             }
-///         }
-///
+///     fn update(&mut self, _message: Self::Message) -> Command<Self::Message> {
 ///         Command::none()
 ///     }
 ///
-///     fn view(&mut self) -> Element<Message> {
-///         Column::new()
-///             .push(
-///                 Button::new(&mut self.increment_button, Text::new("Increment"))
-///                     .on_press(Message::IncrementPressed),
-///             )
-///             .push(
-///                 Text::new(self.value.to_string()).size(50),
-///             )
-///             .push(
-///                 Button::new(&mut self.decrement_button, Text::new("Decrement"))
-///                     .on_press(Message::DecrementPressed),
-///             )
-///             .into()
+///     fn view(&mut self) -> Element<Self::Message> {
+///         Text::new("Hello, world!").into()
 ///     }
 /// }
 /// ```
@@ -101,7 +102,7 @@ pub trait Application: Sized {
     type Flags;
 
     /// Initializes the [`Application`] with the flags provided to
-    /// [`run`] as part of the [`Settings`]:
+    /// [`run`] as part of the [`Settings`].
     ///
     /// Here is where you should return the initial state of your app.
     ///
diff --git a/src/executor.rs b/src/executor.rs
index 6c5425d1..59d59a5a 100644
--- a/src/executor.rs
+++ b/src/executor.rs
@@ -1,5 +1,5 @@
 //! Choose your preferred executor to power your application.
-pub use crate::common::{executor::Null, Executor};
+pub use crate::runtime::{executor::Null, Executor};
 
 pub use platform::Default;
 
diff --git a/src/lib.rs b/src/lib.rs
index 4c7a1310..3343ec0b 100644
--- a/src/lib.rs
+++ b/src/lib.rs
@@ -166,13 +166,14 @@
 //!   1. Draw the resulting user interface.
 //!
 //! # Usage
-//! Take a look at the [`Application`] trait, which streamlines all the process
-//! described above for you!
+//! The [`Application`] and [`Sandbox`] traits should get you started quickly,
+//! streamlining all the process described above!
 //!
 //! [Elm]: https://elm-lang.org/
 //! [The Elm Architecture]: https://guide.elm-lang.org/architecture/
 //! [examples]: https://github.com/hecrj/iced/tree/master/examples
 //! [`Application`]: trait.Application.html
+//! [`Sandbox`]: trait.Sandbox.html
 #![deny(missing_docs)]
 #![deny(missing_debug_implementations)]
 #![deny(unused_results)]
@@ -198,12 +199,12 @@ pub use sandbox::Sandbox;
 pub use settings::Settings;
 
 #[cfg(not(target_arch = "wasm32"))]
-use iced_winit as common;
+use iced_winit as runtime;
 
 #[cfg(target_arch = "wasm32")]
-use iced_web as common;
+use iced_web as runtime;
 
-pub use common::{
+pub use runtime::{
     futures, Align, Background, Color, Command, Font, HorizontalAlignment,
     Length, Point, Size, Subscription, Vector, VerticalAlignment,
 };
diff --git a/src/sandbox.rs b/src/sandbox.rs
index 598a7625..5233ebae 100644
--- a/src/sandbox.rs
+++ b/src/sandbox.rs
@@ -2,78 +2,89 @@ use crate::{executor, Application, Command, Element, Settings, Subscription};
 
 /// A sandboxed [`Application`].
 ///
-/// A [`Sandbox`] is just an [`Application`] that cannot run any asynchronous
-/// actions.
+/// If you are a just getting started with the library, this trait offers a
+/// simpler interface than [`Application`].
 ///
-/// If you do not need to leverage a [`Command`], you can use a [`Sandbox`]
-/// instead of returning a [`Command::none`] everywhere.
+/// Unlike an [`Application`], a [`Sandbox`] cannot run any asynchronous
+/// actions. However, both traits are very similar and upgrading from a
+/// [`Sandbox`] is very straightforward.
+///
+/// Therefore, it is recommended to always start by implementing this trait and
+/// upgrade only once you need to perform asynchronous work.
 ///
 /// [`Application`]: trait.Application.html
 /// [`Sandbox`]: trait.Sandbox.html
 /// [`Command`]: struct.Command.html
 /// [`Command::none`]: struct.Command.html#method.none
 ///
-/// # Example
-/// We can use a [`Sandbox`] to run the [`Counter` example we implemented
-/// before](index.html#overview), instead of an [`Application`]. We just need
-/// to remove the use of [`Command`]:
+/// # Examples
+/// [The repository has a bunch of examples] that use the [`Sandbox`] trait:
+///
+/// - [`bezier_tool`], a Paint-like tool for drawing Bézier curves using
+/// [`lyon`].
+/// - [`counter`], the classic counter example explained in [the overview].
+/// - [`custom_widget`], a demonstration of how to build a custom widget that
+/// draws a circle.
+/// - [`geometry`], a custom widget showcasing how to draw geometry with the
+/// `Mesh2D` primitive in [`iced_wgpu`].
+/// - [`pane_grid`], a grid of panes that can be split, resized, and
+/// reorganized.
+/// - [`progress_bar`], a simple progress bar that can be filled by using a
+/// slider.
+/// - [`styling`], an example showcasing custom styling with a light and dark
+/// theme.
+/// - [`svg`], an application that renders the [Ghostscript Tiger] by leveraging
+/// the [`Svg` widget].
+/// - [`tour`], a simple UI tour that can run both on native platforms and the
+/// web!
+///
+/// [The repository has a bunch of examples]: https://github.com/hecrj/iced/tree/0.1/examples
+/// [`bezier_tool`]: https://github.com/hecrj/iced/tree/0.1/examples/bezier_tool
+/// [`counter`]: https://github.com/hecrj/iced/tree/0.1/examples/counter
+/// [`custom_widget`]: https://github.com/hecrj/iced/tree/0.1/examples/custom_widget
+/// [`geometry`]: https://github.com/hecrj/iced/tree/0.1/examples/geometry
+/// [`pane_grid`]: https://github.com/hecrj/iced/tree/0.1/examples/pane_grid
+/// [`progress_bar`]: https://github.com/hecrj/iced/tree/0.1/examples/progress_bar
+/// [`styling`]: https://github.com/hecrj/iced/tree/0.1/examples/styling
+/// [`svg`]: https://github.com/hecrj/iced/tree/0.1/examples/svg
+/// [`tour`]: https://github.com/hecrj/iced/tree/0.1/examples/tour
+/// [`lyon`]: https://github.com/nical/lyon
+/// [the overview]: index.html#overview
+/// [`iced_wgpu`]: https://github.com/hecrj/iced/tree/0.1/wgpu
+/// [`Svg` widget]: widget/svg/struct.Svg.html
+/// [Ghostscript Tiger]: https://commons.wikimedia.org/wiki/File:Ghostscript_Tiger.svg
+///
+/// ## A simple "Hello, world!"
+///
+/// If you just want to get started, here is a simple [`Sandbox`] that
+/// says "Hello, world!":
 ///
 /// ```no_run
-/// use iced::{button, Button, Column, Element, Sandbox, Settings, Text};
+/// use iced::{Element, Sandbox, Settings, Text};
 ///
 /// pub fn main() {
-///     Counter::run(Settings::default())
-/// }
-///
-/// #[derive(Default)]
-/// struct Counter {
-///     value: i32,
-///     increment_button: button::State,
-///     decrement_button: button::State,
+///     Hello::run(Settings::default())
 /// }
 ///
-/// #[derive(Debug, Clone, Copy)]
-/// enum Message {
-///     IncrementPressed,
-///     DecrementPressed,
-/// }
+/// struct Hello;
 ///
-/// impl Sandbox for Counter {
-///     type Message = Message;
+/// impl Sandbox for Hello {
+///     type Message = ();
 ///
-///     fn new() -> Self {
-///         Self::default()
+///     fn new() -> Hello {
+///         Hello
 ///     }
 ///
 ///     fn title(&self) -> String {
-///         String::from("A simple counter")
+///         String::from("A cool application")
 ///     }
 ///
-///     fn update(&mut self, message: Message) {
-///         match message {
-///             Message::IncrementPressed => {
-///                 self.value += 1;
-///             }
-///             Message::DecrementPressed => {
-///                 self.value -= 1;
-///             }
-///         }
+///     fn update(&mut self, _message: Self::Message) {
+///         // This application has no interactions
 ///     }
 ///
-///     fn view(&mut self) -> Element<Message> {
-///         Column::new()
-///             .push(
-///                 Button::new(&mut self.increment_button, Text::new("Increment"))
-///                     .on_press(Message::IncrementPressed),
-///             )
-///             .push(
-///                 Text::new(self.value.to_string()).size(50),
-///             )
-///             .push(
-///                 Button::new(&mut self.decrement_button, Text::new("Decrement"))
-///                     .on_press(Message::DecrementPressed),
-///             )
-///             .into()
+///     fn view(&mut self) -> Element<Self::Message> {
+///         Text::new("Hello, world!").into()
 ///     }
 /// }
 /// ```
diff --git a/src/settings.rs b/src/settings.rs
index f36ec85f..ea969617 100644
--- a/src/settings.rs
+++ b/src/settings.rs
@@ -13,7 +13,7 @@ pub struct Settings<Flags> {
 
     /// The data needed to initialize an [`Application`].
     ///
-    /// [`Application`]: trait.Application.html
+    /// [`Application`]: ../trait.Application.html
     pub flags: Flags,
 
     /// The bytes of the font that will be used by default.
@@ -26,9 +26,11 @@ pub struct Settings<Flags> {
     /// primitives.
     ///
     /// Enabling it can produce a smoother result in some widgets, like the
-    /// `Canvas`, at a performance cost.
+    /// [`Canvas`], at a performance cost.
     ///
     /// By default, it is disabled.
+    ///
+    /// [`Canvas`]: ../widget/canvas/struct.Canvas.html
     pub antialiasing: bool,
 }
author	Héctor Ramón Jiménez <hector0193@gmail.com>	2020-04-01 04:35:24 +0200
committer	Héctor Ramón Jiménez <hector0193@gmail.com>	2020-04-02 03:44:14 +0200
commit	f5e7e0625eec96f96d9dcbe514198a82bd5a49ec (patch)
tree	ee358df2558c8122498061eac3e9bf509df7e204 /src
parent	4c44517556976454c0598c876addb10b88515cda (diff)
download	iced-f5e7e0625eec96f96d9dcbe514198a82bd5a49ec.tar.gz iced-f5e7e0625eec96f96d9dcbe514198a82bd5a49ec.tar.bz2 iced-f5e7e0625eec96f96d9dcbe514198a82bd5a49ec.zip