Add documentation for examples

The examples include a README located in `examples/README.md`, which
contains instructions for running these examples.

They act as a simple form of tutorial to the library, without getting
into too many details.

2 files changed, 59 insertions, 9 deletions

diff --git a/src/ext/cache/mod.rs b/src/ext/cache/mod.rs
index 2272178..2778d6b 100644
--- a/src/ext/cache/mod.rs
+++ b/src/ext/cache/mod.rs
@@ -2,7 +2,7 @@
 //! data from the event is possible.
 //!
 //! This acts as a hot cache, to avoid making requests over the REST API through
-//! the [`http`] module where possible. All fields are public, and do not have
+//! the [`rest`] module where possible. All fields are public, and do not have
 //! getters, to allow you more flexibility with the stored data. However, this
 //! allows data to be "corrupted", and _may or may not_ cause misfunctions
 //! within the library. Mutate data at your own discretion.
@@ -22,7 +22,7 @@
 //! This allows you to save a step, by only needing to perform the
 //! [`Context::get_channel`] call and not need to first search through the cache
 //! - and if not found - _then_ perform an HTTP request through the Context or
-//! [`http`] module.
+//! [`rest`] module.
 //!
 //! Additionally, note that some information received through events can _not_
 //! be retrieved through the REST API. This is information such as [`Role`]s in
@@ -74,7 +74,7 @@
 //! [`Role`]: ../../model/struct.Role.html
 //! [`Shard`]: ../../client/gateway/struct.Shard.html
 //! [`client::CACHE`]: ../../client/struct.CACHE.html
-//! [`http`]: ../../client/http/index.html
+//! [`rest`]: ../../client/rest/index.html
 
 use std::collections::hash_map::Entry;
 use std::collections::HashMap;
diff --git a/src/lib.rs b/src/lib.rs
index 761ef86..8afb89f 100644
--- a/src/lib.rs
+++ b/src/lib.rs
@@ -14,10 +14,9 @@
 //! [`Context`], giving information about the event. See the
 //! [client's module-level documentation].
 //!
-//! The [`Connection`] is transparently handled by the library, removing
+//! The [`Shard`] is transparently handled by the library, removing
 //! unnecessary complexity. Sharded connections are automatically handled for
-//! you. See the [Connection's documentation][`Connection`] for more
-//! information.
+//! you. See the [gateway's documentation][gateway docs] for more information.
 //!
 //! A [`Cache`] is also provided for you. This will be updated automatically for
 //! you as data is received from the Discord API via events. When calling a
@@ -30,12 +29,56 @@
 //! need to be sure that some information piece is sanctioned by Discord, refer
 //! to their own documentation.
 //!
+//! # Features
+//!
+//! Features can be enabled or disabled by configuring the library through
+//! Cargo.toml:
+//!
+//! ```toml
+//! [dependencies.serenity]
+//! git = "https://github.com/zeyla/serenity.rs.git"
+//! default-features = false
+//! features = ["pick", "your", "feature", "names", "here"]
+//! ```
+//!
+//! The following is a full list of features:
+//!
+//! - **cache**: The cache will store information about guilds, channels, users,
+//! and other data, to avoid performing REST requests. If you are low on RAM, do
+//! not enable this;
+//! - **framework**: Enables the framework, which is a utility to allow simple
+//! command parsing, before/after command execution, prefix setting, and more;
+//! - **methods**: Enables compilation of extra methods on struct
+//! implementations, such as `Message::delete()`, `Message::reply()`,
+//! `Guild::edit()`, and more. Without this enabled, requests will need to go
+//! through the [`Context`] or [`rest`] module, which are slightly less
+//! efficient from a development standpoint, and do not automatically perform
+//! permission checking;
+//! - **voice**: Enables compilation of voice support, so that voice channels
+//! can be connected to and audio can be sent/received.
+//!
 //! # Dependencies
 //!
 //! Serenity requires the following dependencies:
 //!
 //! - openssl
 //!
+//! ### Voice
+//!
+//! The following dependencies all require the **voice** feature to be enabled
+//! in your Cargo.toml:
+//!
+//! - libsodium (Arch: `community/libsodium`)
+//! - opus (Arch: `extra/opus`)
+//!
+//! Voice+ffmpeg:
+//!
+//! - ffmpeg (Arch: `extra/ffmpeg`)
+//!
+//! Voice+youtube-dl:
+//!
+//! - youtube-dl (Arch: `community/youtube-dl`)
+//!
 //! # Example Bot
 //!
 //! A basic ping-pong bot looks like:
@@ -56,24 +99,31 @@
 //!             let _ = message.reply("Pong!");
 //!         }));
 //!
-//!     // start listening for events by starting a connection
+//!     // start listening for events by starting a single shard
 //!     let _ = client.start();
 //! }
 //! ```
+//! ### Full Examples
+//!
+//! Full examples, detailing and explaining usage of the basic functionality of the
+//! library, can be found in the [`examples`] directory.
 //!
 //! [`Cache`]: ext/cache/struct.Cache.html
 //! [`Client::login_bot`]: client/struct.Client.html#method.login_bot
 //! [`Client::login_user`]: client/struct.Client.html#method.login_user
 //! [`Client::on_message`]: client/struct.Client.html#method.on_message
-//! [`Connection`]: client/struct.Connection.html
 //! [`Context`]: client/struct.Context.html
 //! [`Event`]: model/event/enum.Event.html
 //! [`Event::MessageCreate`]: model/event/enum.Event.html#variant.MessageCreate
+//! [`Shard`]: client/struct.Shard.html
+//! [`examples`]: https://github.com/zeyla/serenity.rs.git/blob/master/examples
+//! [`rest`]: client/rest/index.html
+//! [`validate_token`]: client/fn.validate_token.html
 //! [cache docs]: ext/cache/index.html
 //! [client's module-level documentation]: client/index.html
 //! [docs]: https://discordapp.com/developers/docs/intro
 //! [examples]: https://github.com/zeyla/serenity.rs/tree/master/examples
-//! [`validate_token`]: client/fn.validate_token.html
+//! [gateway docs]: client/gateway/index.html
 #![allow(doc_markdown, inline_always, unknown_lints)]
 #![doc(html_logo_url = "https://docs.austinhellyer.me/serenity.rs/docs_header.png")]
 #![warn(enum_glob_use, if_not_else)]