Restructure modules

Modules are now separated into a fashion where the library can be used
for most use cases, without needing to compile the rest.

The core of serenity, with no features enabled, contains only the
struct (model) definitions, constants, and prelude. Models do not have
most functions compiled in, as that is separated into the `model`
feature.

The `client` module has been split into 3 modules: `client`, `gateway`,
and `http`.

`http` contains functions to interact with the REST API. `gateway`
contains the Shard to interact with the gateway, requiring `http` for
retrieving the gateway URL. `client` requires both of the other features
and acts as an abstracted interface over both the gateway and REST APIs,
handling the event loop.

The `builder` module has been separated from `utils`, and can now be
optionally compiled in. It and the `http` feature are required by the
`model` feature due to a large number of methods requiring access to
them.

`utils` now contains a number of utilities, such as the Colour struct, the
`MessageBuilder`, and mention parsing functions.

Each of the original `ext` modules are still featured, with `cache` not
requiring any feature to be enabled, `framework` requiring the `client`,
`model`, and `utils`, and `voice` requiring `gateway`.

In total the features and their requirements are:

- `builder`: none
- `cache`: none
- `client`: `gateway`, `http`
- `framework`: `client`, `model`, `utils`
- `gateway`: `http`
- `http`: none
- `model`: `builder`, `http`
- `utils`: none
- `voice`: `gateway`

The default features are `builder`, `cache`, `client`, `framework`,
`gateway`, `model`, `http`, and `utils`.

To help with forwards compatibility, modules have been re-exported from
their original locations.

1 files changed, 59 insertions, 0 deletions

diff --git a/src/gateway/mod.rs b/src/gateway/mod.rs
new file mode 100644
index 0000000..38cdaa1
--- /dev/null
+++ b/src/gateway/mod.rs
@@ -0,0 +1,59 @@
+//! The gateway module contains the pieces - primarily the `Shard` -
+//! responsible for maintaing a WebSocket connection with Discord.
+//!
+//! A shard is an interface for the lower-level receiver and sender. It provides
+//! what can otherwise be thought of as "sugar methods". A shard represents a
+//! single connection to Discord. If acting as a [`Bot`] user, you can make
+//! use of a method named "sharding" to have multiple shards, potentially
+//! offloading some server load to another server(s).
+//!
+//! # Sharding
+//!
+//! Sharding is a method to split portions of bots into separate processes. This
+//! is an enforced strategy by Discord once a bot reaches a certain number of
+//! guilds (2500). Once this number is reached, a bot must be sharded in a way
+//! that only 2500 guilds maximum may be allocated per shard.
+//!
+//! The "recommended" number of guilds per shard is _around_ 1000. Sharding can
+//! be useful for splitting processes across separate servers. Often you may
+//! want some or all shards to be in the same process, allowing for a shared
+//! State. This is possible through this library.
+//!
+//! See [Discord's documentation][docs] for more information.
+//!
+//! If you are not using a bot account or do not require sharding - such as for
+//! a small bot - then use [`Client::start`].
+//!
+//! There are a few methods of sharding available:
+//!
+//! - [`Client::start_autosharded`]: retrieves the number of shards Discord
+//! recommends using from the API, and then automatically starts that number of
+//! shards.
+//! - [`Client::start_shard`]: starts a single shard for use in the instance,
+//! handled by the instance of the Client. Use this if you only want 1 shard
+//! handled by this instance.
+//! - [`Client::start_shards`]: starts all shards in this instance. This is best
+//! for when you want a completely shared State.
+//! - [`Client::start_shard_range`]: start a range of shards within this
+//! instance. This should be used when you, for example, want to split 10 shards
+//! across 3 instances.
+//!
+//! **Note**: User accounts can not shard. Use [`Client::start`].
+//!
+//! [`Bot`]: ../enum.LoginType.html#variant.Bot
+//! [`Client`]: ../struct.Client.html
+//! [`Client::start`]: ../struct.Client.html#method.start
+//! [`Client::start_autosharded`]: ../struct.Client.html#method.start_autosharded
+//! [`Client::start_shard`]: ../struct.Client.html#method.start_shard
+//! [`Client::start_shard_range`]: ../struct.Client.html#method.start_shard_range
+//! [`Client::start_shards`]: ../struct.Client.html#method.start_shards
+//! [docs]: https://discordapp.com/developers/docs/topics/gateway#sharding
+
+mod error;
+mod prep;
+mod shard;
+mod status;
+
+pub use self::error::Error as GatewayError;
+pub use self::shard::Shard;
+pub use self::status::Status as GatewayStatus;