Add slightly more documentation

3 files changed, 209 insertions, 0 deletions

diff --git a/src/client/error.rs b/src/client/error.rs
index 1eaa2c6..30d3c27 100644
--- a/src/client/error.rs
+++ b/src/client/error.rs
@@ -57,6 +57,11 @@ pub enum Error {
     /// When attempting to delete a number of days' worth of messages that is
     /// not allowed.
     DeleteMessageDaysAmount(u8),
+    /// When there is an error from Discord for a specific action, such as
+    /// [`ErrorCode::EditByOtherAuthor`]. This is a friendlier representation of
+    /// the numerical error codes Discord provides.
+    ///
+    /// [`ErrorCode::EditByOtherAuthor`]: rest/enum.ErrorCode.html#variant.EditByOtherAuthor
     ErrorCode(ErrorCode),
     /// When there was an error retrieving the gateway URI from the REST API.
     Gateway,
@@ -67,6 +72,7 @@ pub enum Error {
     /// [`GuildId`]: ../model/struct.GuildId.html
     /// [`Cache`]: ../ext/cache/struct.Cache.html
     GuildNotFound,
+    /// An indicator that an unknown opcode was received from the gateway.
     InvalidOpCode,
     /// When attempting to perform an action which is only available to user
     /// accounts.
@@ -123,6 +129,8 @@ pub enum Error {
     ///
     /// [`Context::edit_role`]: struct.Context.html#method.edit_role
     RecordNotFound,
+    /// When a shard has completely failed to reboot after resume and/or
+    /// reconnect attempts.
     ShardBootFailure,
     /// When the shard being retrieved from within the Client could not be
     /// found after being inserted into the Client's internal vector of
diff --git a/src/client/gateway/shard.rs b/src/client/gateway/shard.rs
index a51c2dc..e4c4720 100644
--- a/src/client/gateway/shard.rs
+++ b/src/client/gateway/shard.rs
@@ -477,6 +477,8 @@ impl Shard {
         Ok(())
     }
 
+    /// Uncleanly shuts down the receiver by not sending a close code.
+    #[doc(hidden)]
     pub fn shutdown(receiver: &mut Receiver<WebSocketStream>) -> Result<()> {
         let r = receiver.get_mut().get_mut();
 
diff --git a/src/client/rest/ratelimiting.rs b/src/client/rest/ratelimiting.rs
index 8e3cce7..00c374f 100644
--- a/src/client/rest/ratelimiting.rs
+++ b/src/client/rest/ratelimiting.rs
@@ -99,59 +99,258 @@ lazy_static! {
 /// [`rest`]: ../index.html
 #[derive(Clone, Copy, Debug, Eq, Hash, PartialEq)]
 pub enum Route {
+    /// Route for the `/channels/:channel_id` path.
+    ///
+    /// The data is the relevant [`ChannelId`].
+    ///
+    /// [`ChannelId`]: ../../model/struct.ChannelId.html
     ChannelsId(u64),
+    /// Route for the `/channels/:channel_id/invites` path.
+    ///
+    /// The data is the relevant [`ChannelId`].
+    ///
+    /// [`ChannelId`]: ../../model/struct.ChannelId.html
     ChannelsIdInvites(u64),
+    /// Route for the `/channels/:channel_id/messages` path.
+    ///
+    /// The data is the relevant [`ChannelId`].
+    ///
+    /// [`ChannelId`]: ../../model/struct.ChannelId.html
     ChannelsIdMessages(u64),
+    /// Route for the `/channels/:channel_id/messages/bulk-delete` path.
+    ///
+    /// The data is the relevant [`ChannelId`].
+    ///
+    /// [`ChannelId`]: ../../model/struct.ChannelId.html
     ChannelsIdMessagesBulkDelete(u64),
+    /// Route for the `/channels/:channel_id/messages/:message_id` path.
+    ///
+    /// The data is the relevant [`ChannelId`].
+    ///
+    /// [`ChannelId`]: ../../model/struct.ChannelId.html
     // This route is a unique case. The ratelimit for message _deletions_ is
     // different than the overall route ratelimit.
     //
     // Refer to the docs on [Rate Limits] in the yellow warning section.
     //
+    // Additionally, this needs to be a `LightMethod` from the parent module
+    // and _not_ a `hyper` `Method` due to `hyper`'s not deriving `Copy`.
+    //
     // [Rate Limits]: https://discordapp.com/developers/docs/topics/rate-limits
     ChannelsIdMessagesId(LightMethod, u64),
+    /// Route for the `/channels/:channel_id/messages/:message_id/ack` path.
+    ///
+    /// The data is the relevant [`ChannelId`].
+    ///
+    /// [`ChannelId`]: ../../model/struct.ChannelId.html
     ChannelsIdMessagesIdAck(u64),
+    /// Route for the `/channels/:channel_id/messages/:message_id/reactions`
+    /// path.
+    ///
+    /// The data is the relevant [`ChannelId`].
+    ///
+    /// [`ChannelId`]: ../../model/struct.ChannelId.html
     ChannelsIdMessagesIdReactions(u64),
+    /// Route for the
+    /// `/channels/:channel_id/messages/:message_id/reactions/:reaction/@me`
+    /// path.
+    ///
+    /// The data is the relevant [`ChannelId`].
+    ///
+    /// [`ChannelId`]: ../../model/struct.ChannelId.html
     ChannelsIdMessagesIdReactionsUserIdType(u64),
+    /// Route for the `/channels/:channel_id/messages/search` path.
+    ///
+    /// The data is the relevant [`ChannelId`].
+    ///
+    /// [`ChannelId`]: ../../model/struct.ChannelId.html
     ChannelsIdMessagesSearch(u64),
+    /// Route for the `/channels/:channel_id/permissions/:target_id` path.
+    ///
+    /// The data is the relevant [`ChannelId`].
+    ///
+    /// [`ChannelId`]: ../../model/struct.ChannelId.html
     ChannelsIdPermissionsOverwriteId(u64),
+    /// Route for the `/channels/:channel_id/pins` path.
+    ///
+    /// The data is the relevant [`ChannelId`].
+    ///
+    /// [`ChannelId`]: ../../model/struct.ChannelId.html
     ChannelsIdPins(u64),
+    /// Route for the `/channels/:channel_id/pins/:message_id` path.
+    ///
+    /// The data is the relevant [`ChannelId`].
+    ///
+    /// [`ChannelId`]: ../../model/struct.ChannelId.html
     ChannelsIdPinsMessageId(u64),
+    /// Route for the `/channels/:channel_id/typing` path.
+    ///
+    /// The data is the relevant [`ChannelId`].
+    ///
+    /// [`ChannelId`]: ../../model/struct.ChannelId.html
     ChannelsIdTyping(u64),
+    /// Route for the `/channels/:channel_id/webhooks` path.
+    ///
+    /// The data is the relevant [`ChannelId`].
+    ///
+    /// [`ChannelId`]: ../../model/struct.ChannelId.html
     ChannelsIdWebhooks(u64),
+    /// Route for the `/gateway` path.
     Gateway,
+    /// Route for the `/gateway/bot` path.
     GatewayBot,
+    /// Route for the `/guilds` path.
     Guilds,
+    /// Route for the `/guilds/:guild_id` path.
+    ///
+    /// The data is the relevant [`GuildId`].
+    ///
+    /// [`GuildId`]: struct.GuildId.html
     GuildsId(u64),
+    /// Route for the `/guilds/:guild_id/bans` path.
+    ///
+    /// The data is the relevant [`GuildId`].
+    ///
+    /// [`GuildId`]: struct.GuildId.html
     GuildsIdBans(u64),
+    /// Route for the `/guilds/:guild_id/bans/:user_id` path.
+    ///
+    /// The data is the relevant [`GuildId`].
+    ///
+    /// [`GuildId`]: struct.GuildId.html
     GuildsIdBansUserId(u64),
+    /// Route for the `/guilds/:guild_id/channels/:channel_id` path.
+    ///
+    /// The data is the relevant [`GuildId`].
+    ///
+    /// [`GuildId`]: struct.GuildId.html
     GuildsIdChannels(u64),
+    /// Route for the `/guilds/:guild_id/embed` path.
+    ///
+    /// The data is the relevant [`GuildId`].
+    ///
+    /// [`GuildId`]: struct.GuildId.html
     GuildsIdEmbed(u64),
+    /// Route for the `/guilds/:guild_id/emojis` path.
+    ///
+    /// The data is the relevant [`GuildId`].
+    ///
+    /// [`GuildId`]: struct.GuildId.html
     GuildsIdEmojis(u64),
+    /// Route for the `/guilds/:guild_id/emojis/:emoji_id` path.
+    ///
+    /// The data is the relevant [`GuildId`].
+    ///
+    /// [`GuildId`]: struct.GuildId.html
     GuildsIdEmojisId(u64),
+    /// Route for the `/guilds/:guild_id/integrations` path.
+    ///
+    /// The data is the relevant [`GuildId`].
+    ///
+    /// [`GuildId`]: struct.GuildId.html
     GuildsIdIntegrations(u64),
+    /// Route for the `/guilds/:guild_id/integrations/:integration_id` path.
+    ///
+    /// The data is the relevant [`GuildId`].
+    ///
+    /// [`GuildId`]: struct.GuildId.html
     GuildsIdIntegrationsId(u64),
+    /// Route for the `/guilds/:guild_id/integrations/:integration_id/sync`
+    /// path.
+    ///
+    /// The data is the relevant [`GuildId`].
+    ///
+    /// [`GuildId`]: struct.GuildId.html
     GuildsIdIntegrationsIdSync(u64),
+    /// Route for the `/guilds/:guild_id/invites` path.
+    ///
+    /// The data is the relevant [`GuildId`].
+    ///
+    /// [`GuildId`]: struct.GuildId.html
     GuildsIdInvites(u64),
+    /// Route for the `/guilds/:guild_id/members` path.
+    ///
+    /// The data is the relevant [`GuildId`].
+    ///
+    /// [`GuildId`]: struct.GuildId.html
     GuildsIdMembers(u64),
+    /// Route for the `/guilds/:guild_id/members/:user_id` path.
+    ///
+    /// The data is the relevant [`GuildId`].
+    ///
+    /// [`GuildId`]: struct.GuildId.html
     GuildsIdMembersId(u64),
+    /// Route for the `/guilds/:guild_id/members/:user_id/roles/:role_id` path.
+    ///
+    /// The data is the relevant [`GuildId`].
+    ///
+    /// [`GuildId`]: struct.GuildId.html
     GuildsIdMembersIdRolesId(u64),
+    /// Route for the `/guilds/:guild_id/members/@me/nick` path.
+    ///
+    /// The data is the relevant [`GuildId`].
+    ///
+    /// [`GuildId`]: struct.GuildId.html
     GuildsIdMembersMeNick(u64),
+    /// Route for the `/guilds/:guild_id/messages/search` path.
+    ///
+    /// The data is the relevant [`GuildId`].
+    ///
+    /// [`GuildId`]: struct.GuildId.html
     GuildsIdMessagesSearch(u64),
+    /// Route for the `/guilds/:guild_id/prune` path.
+    ///
+    /// The data is the relevant [`GuildId`].
+    ///
+    /// [`GuildId`]: struct.GuildId.html
     GuildsIdPrune(u64),
+    /// Route for the `/guilds/:guild_id/regions` path.
+    ///
+    /// The data is the relevant [`GuildId`].
+    ///
+    /// [`GuildId`]: struct.GuildId.html
     GuildsIdRegions(u64),
+    /// Route for the `/guilds/:guild_id/roles` path.
+    ///
+    /// The data is the relevant [`GuildId`].
+    ///
+    /// [`GuildId`]: struct.GuildId.html
     GuildsIdRoles(u64),
+    /// Route for the `/guilds/:guild_id/roles/:role_id` path.
+    ///
+    /// The data is the relevant [`GuildId`].
+    ///
+    /// [`GuildId`]: struct.GuildId.html
     GuildsIdRolesId(u64),
+    /// Route for the `/guilds/:guild_id/webhooks` path.
+    ///
+    /// The data is the relevant [`GuildId`].
+    ///
+    /// [`GuildId`]: struct.GuildId.html
     GuildsIdWebhooks(u64),
+    /// Route for the `/invites/:code` path.
     InvitesCode,
+    /// Route for the `/users/:user_id` path.
     UsersId,
+    /// Route for the `/users/@me` path.
     UsersMe,
+    /// Route for the `/users/@me/channels` path.
     UsersMeChannels,
+    /// Route for the `/users/@me/connections` path.
     UsersMeConnections,
+    /// Route for the `/users/@me/guilds` path.
     UsersMeGuilds,
+    /// Route for the `/users/@me/guilds/:guild_id` path.
     UsersMeGuildsId,
+    /// Route for the `/voice/regions` path.
     VoiceRegions,
+    /// Route for the `/webhooks/:webhook_id` path.
     WebhooksId,
+    /// Route where no ratelimit headers are in place (i.e. user account-only
+    /// routes).
+    ///
+    /// This is a special case, in that if the route is `None` then pre- and
+    /// post-hooks are not executed.
     None,
 }