Write more documentation

6 files changed, 25 insertions, 16 deletions

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.
 ///