Write more documentation

7 files changed, 32 insertions, 23 deletions

diff --git a/README.md b/README.md
index 25934252..de2fd010 100644
--- a/README.md
+++ b/README.md
@@ -4,7 +4,8 @@
 [![Crates.io](https://img.shields.io/crates/v/iced.svg)](https://crates.io/crates/iced)
 [![License](https://img.shields.io/crates/l/iced.svg)](https://github.com/hecrj/iced/blob/master/LICENSE)
 
-A simple GUI runtime for Rust, heavily inspired by [Elm].
+A renderer-agnostic GUI library for Rust focused on simplicity and type-safety.
+Inspired by [Elm].
 
 __Iced is in a very early stage of development.__ Many [basic features are still
 missing] and there are probably _many_ bugs. [Feel free to contribute!]
@@ -18,12 +19,11 @@ missing] and there are probably _many_ bugs. [Feel free to contribute!]
 [gui_gfycat]: https://gfycat.com/gloomyweakhammerheadshark
 
 ## Features
-  * Simple, easy-to-use API
+  * Simple, easy-to-use, renderer-agnostic API
   * Responsive, flexbox-based layouting
   * Type-safe, reactive programming model
   * Built-in widgets
   * Custom widget support
-  * Renderer-agnostic runtime
 
 ## Installation
 Add `iced` as a dependency in your `Cargo.toml`:
@@ -67,8 +67,8 @@ struct Counter {
 }
 ```
 
-Now that we have state, what are the user interactions we care about? The
-button presses! These are our __messages__:
+Now that we have state... When will it change? When either button is pressed!
+These user interactions are our __messages__:
 
 ```rust
 #[derive(Debug, Clone, Copy)]
@@ -108,7 +108,7 @@ impl Counter {
 }
 ```
 
-Finally, we need to be able to react to the __messages__ and mutate our
+Finally, we need to be able to react to the __messages__ and change our
 __state__ accordingly in our __update logic__:
 
 ```rust
@@ -131,7 +131,7 @@ impl Counter {
 And that's everything! We just wrote a whole user interface. Iced is now able
 to:
 
-  1. Take the result of our __view logic__ and build a user interface.
+  1. Take the result of our __view logic__ and layout its widgets.
   1. Process events from our system and produce __messages__ for our
      __update logic__.
   1. Draw the resulting user interface using our chosen __renderer__.
diff --git a/src/lib.rs b/src/lib.rs
index d4089ac8..9dab0470 100644
--- a/src/lib.rs
+++ b/src/lib.rs
@@ -1,12 +1,12 @@
-//! Iced is a simple GUI runtime for Rust, heavily inspired by [Elm].
+//! Iced is a renderer-agnostic GUI library for Rust focused on simplicity and
+//! type-safety. Inspired by [Elm].
 //!
 //! # Features
-//!   * Simple, easy-to-use API
+//!   * Simple, easy-to-use, renderer-agnostic API
 //!   * Responsive, flexbox-based layouting
 //!   * Type-safe, reactive programming model
-//!   * Many built-in widgets
+//!   * Built-in widgets
 //!   * Custom widget support
-//!   * Renderer-agnostic runtime
 //!
 //! Check out the [repository] and the [examples] for more details!
 //!
@@ -43,8 +43,8 @@
 //! }
 //! ```
 //!
-//! Now that we have state, what are the user interactions we care about? The
-//! button presses! These are our __messages__:
+//! Now that we have state... When will it change? When either button is pressed!
+//! These user interactions are our __messages__:
 //!
 //! ```
 //! #[derive(Debug, Clone, Copy)]
@@ -139,7 +139,7 @@
 //! }
 //! ```
 //!
-//! Finally, we need to be able to react to the __messages__ and mutate our
+//! Finally, we need to be able to react to the __messages__ and change our
 //! __state__ accordingly in our __update logic__:
 //!
 //! ```
diff --git a/src/point.rs b/src/point.rs
index dbb6027e..8f172689 100644
--- a/src/point.rs
+++ b/src/point.rs
@@ -1 +1,2 @@
+/// A 2D point.
 pub type Point = nalgebra::Point2<f32>;
diff --git a/src/user_interface.rs b/src/user_interface.rs
index 0a36e151..cb8d05ae 100644
--- a/src/user_interface.rs
+++ b/src/user_interface.rs
@@ -3,6 +3,7 @@ use crate::{input::mouse, Column, Element, Event, Layout, MouseCursor, Point};
 use std::hash::Hasher;
 use stretch::result;
 
+/// A set of interactive graphical elements with a specific layout.
 pub struct UserInterface<'a, Message, Renderer> {
     hash: u64,
     root: Element<'a, Message, Renderer>,
diff --git a/src/widget.rs b/src/widget.rs
index c3df3bc1..cd3ff7a2 100644
--- a/src/widget.rs
+++ b/src/widget.rs
@@ -1,8 +1,14 @@
 //! Use the built-in widgets or create your own!
 //!
-//! # Customization
-//! Every drawable widget has its own module with a `Renderer` trait that must
-//! be implemented by a renderer before being able to use it as a [`Widget`].
+//! # Built-in widgets
+//! Every built-in drawable widget has its own module with a `Renderer` trait
+//! that must be implemented by an [`iced::Renderer`] before being able to use
+//! it as a [`Widget`].
+//!
+//! # Custom widgets
+//! If you want to implement a custom widget, you simply need to implement the
+//! [`Widget`] trait. You can use the API of the built-in widgets as a guide or
+//! source of inspiration.
 //!
 //! # Re-exports
 //! For convenience, the contents of this module are available at the root
@@ -13,6 +19,7 @@
 //! ```
 //!
 //! [`Widget`]: trait.Widget.html
+//! [`iced::Renderer`]: ../trait.Renderer.html
 mod column;
 mod row;
 
@@ -78,8 +85,8 @@ pub trait Widget<Message, Renderer>: std::fmt::Debug {
     /// its value cannot affect the overall [`Layout`] of the user interface.
     ///
     /// [`Widget`]: trait.Widget.html
-    /// [`Layout`]: struct.Layout.html
-    /// [`Text`]: ../widget/text/struct.Text.html
+    /// [`Layout`]: ../struct.Layout.html
+    /// [`Text`]: text/struct.Text.html
     fn hash(&self, state: &mut Hasher);
 
     /// Processes a runtime [`Event`].
@@ -93,9 +100,9 @@ pub trait Widget<Message, Renderer>: std::fmt::Debug {
     ///
     /// By default, it does nothing.
     ///
-    /// [`Event`]: enum.Event.html
+    /// [`Event`]: ../enum.Event.html
     /// [`Widget`]: trait.Widget.html
-    /// [`Layout`]: struct.Layout.html
+    /// [`Layout`]: ../struct.Layout.html
     fn on_event(
         &mut self,
         _event: Event,
diff --git a/src/widget/column.rs b/src/widget/column.rs
index 291019b2..d2688912 100644
--- a/src/widget/column.rs
+++ b/src/widget/column.rs
@@ -5,7 +5,7 @@ use crate::{
     Style, Widget,
 };
 
-/// A container that places its contents vertically.
+/// A container that distributes its contents vertically.
 ///
 /// A [`Column`] will try to fill the horizontal space of its container.
 ///
diff --git a/src/widget/row.rs b/src/widget/row.rs
index 6265739a..c4121157 100644
--- a/src/widget/row.rs
+++ b/src/widget/row.rs
@@ -5,7 +5,7 @@ use crate::{
     Style, Widget,
 };
 
-/// A container that places its contents horizontally.
+/// A container that distributes its contents horizontally.
 ///
 /// A [`Row`] will try to fill the horizontal space of its container.
 ///