Add documentation for models

23 files changed, 217 insertions, 21 deletions

diff --git a/definitions/enums/relationship_type.yml b/definitions/enums/relationship_type.yml
index 68baed4..4c42af7 100644
--- a/definitions/enums/relationship_type.yml
+++ b/definitions/enums/relationship_type.yml
@@ -1,13 +1,19 @@
 ---
 name: RelationshipType
+description: The type of a relationship between two users.
 variants:
   - variant: Blocked
+    description: When one user blocked the other one.
     number: 2
   - variant: Friends
+    description: When users are friends.
     number: 1
   - variant: IncomingRequest
+    description: When an incoming friend request was received.
     number: 3
   - variant: Ignored
+    description: When a friend request was ignored.
     number: 0
   - variant: OutgoingRequest
+    description: When an outgoing friend request was sent.
     number: 4
diff --git a/definitions/enums/verification_level.yml b/definitions/enums/verification_level.yml
index ded2db9..59e138e 100644
--- a/definitions/enums/verification_level.yml
+++ b/definitions/enums/verification_level.yml
@@ -7,10 +7,17 @@ description: >
     [`Guild`]: struct.Guild.html
 variants:
   - variant: High
+    description: >
+      Requires a verified e-mail and being registered for more than 10 minutes.
+      This is stylised as tableflip in the client.
     number: 3
   - variant: Low
+    description: Requires a verified e-mail.
     number: 1
   - variant: Medium
+    description: >
+      Requires a verified e-mail and being registered for more than 5 minutes.
     number: 2
   - variant: None
+    description: No verification.
     number: 0
diff --git a/definitions/structs/embed.yml b/definitions/structs/embed.yml
index 312bec9..158e374 100644
--- a/definitions/structs/embed.yml
+++ b/definitions/structs/embed.yml
@@ -1,6 +1,19 @@
 ---
 name: Embed
-description: An embed in a message, such as for a URL or an attachment.
+description: >
+  Represents a rich embed which allows using richer markdown,
+  multiple columns and more. This was heavily inspired by
+  [slack's attachments].
+
+
+  You can include an attachment in your own message by a user or a bot,
+  or in a webhook. They can be edited, too.
+
+
+  **Note**: Maximum amount of characters you can put is 256 in a field name,
+  1024 in a field value, and 2048 in a description.
+
+    [slack's attachments]: https://api.slack.com/docs/message-attachments
 fields:
   - name: author
     description: Author information about the embed.
diff --git a/definitions/structs/emoji.yml b/definitions/structs/emoji.yml
index fa85ae2..8a69cf1 100644
--- a/definitions/structs/emoji.yml
+++ b/definitions/structs/emoji.yml
@@ -1,12 +1,16 @@
 ---
 name: Emoji
-description: "A custom emoji for a guild."
+description: >
+  Represents a custom guild emoji, which can either be created using the API,
+  or via an integration. Emojis created using the API only work within the guild
+  it was created in.
 fields:
   - name: id
     description: "The Id of the emoji."
     type: EmojiId
   - name: name
-    description: "The name of the emoji."
+    description: "The name of the emoji. It must be at least 2 characters
+      long and can only contain alphanumeric characters and underscores."
     type: string
   - name: managed
     description: "Whether the emoji is managed via an
diff --git a/definitions/structs/game.yml b/definitions/structs/game.yml
index 0d26bb9..afd02ff 100644
--- a/definitions/structs/game.yml
+++ b/definitions/structs/game.yml
@@ -1,14 +1,19 @@
 ---
 name: Game
-description: Information about a game that a user is playing
+description: >
+  Represents a game that a a user is playing, or streaming in the case that a
+  stream link is provided.
 fields:
   - name: kind
+    description: The type of game status.
     default: GameType::Playing
     from: type
     type: GameType
   - name: name
+    description: The name of the game that's being played.
     type: string
   - name: url
+    description: Stream URL if the `kind` is `Streaming`.
     optional: true
     type: string
 decode: false
diff --git a/definitions/structs/group.yml b/definitions/structs/group.yml
index b55da91..ba813d3 100644
--- a/definitions/structs/group.yml
+++ b/definitions/structs/group.yml
@@ -1,25 +1,35 @@
 ---
 name: Group
-description: A group channel, potentially including other users, separate from a server.
+description: >
+  A group channel, potentially including other users, separate from a [`Guild`].
+
+    [`Guild`]: struct.Guild.html
 fields:
   - name: channel_id
+    description: The Id of the group channel.
     from: id
     type: ChannelId
   - name: icon
+    description: The optional icon of the group channel.
     optional: true
     type: string
   - name: last_message_id
+    description: The Id of the last message sent.
     optional: true
     type: MessageId
   - name: last_pin_timestamp
+    description: Timestamp of the latest pinned message.
     optional: true
     type: string
   - name: name
+    description: The name of the group channel.
     optional: true
     type: string
   - name: owner_id
+    description: The Id of the group channel creator.
     type: UserId
   - name: recipients
+    description: Group channel's members.
     custom: decode_users
     t: UserId, User
     type: hashmap
diff --git a/definitions/structs/guild.yml b/definitions/structs/guild.yml
index b6caf28..35104b3 100644
--- a/definitions/structs/guild.yml
+++ b/definitions/structs/guild.yml
@@ -1,61 +1,106 @@
 ---
 name: Guild
-description: "Live server information"
+description: >
+  Live information about a Discord guild such as channels, emojis, etc.
 fields:
   - name: afk_channel_id
+    description: Id of a voice channel that's considered AFK.
     optional: true
     type: ChannelId
   - name: afk_timeout
+    description: >
+      The amount of seconds a user can not show any activity in a voice
+      channel before being moved to an AFK channel if one exists.
     type: u64
   - name: channels
+    description: >
+      All voice and text channels a guild has. This gives all of them
+      regardless of permissions.
     t: ChannelId, GuildChannel
     type: hashmap
   - name: default_message_notifications
+    description: >
+      Lets you know if notifications for all messages are enabled by
+      default in the guild.
     type: u64
   - name: emojis
+    description: >
+      All custom emojis of a guild. Such are made using the API or
+      Twitch integrations.
     custom: decode_emojis
     t: EmojiId, Emoji
     type: hashmap
   - name: features
+    description: >
+      VIP guild features a guild has. Can be obtained through
+      [Discord Partnership] website.
+
+        [Discord Partnership]: https://discordapp.com/partners
     array: true
     type: Feature
   - name: icon
+    description: Optional guild icon that appears in sidebar.
     optional: true
     type: string
   - name: id
+    description: >
+      Guild's Id which is also the Id of the default role and channel.
     type: GuildId
   - name: joined_at
     type: string
   - name: large
+    description: >
+      Set to true if guild has a lot of users.
+      It means that guild members aren't sent on ready event.
     type: bool
   - name: member_count
+    description: >
+      The amount of members in guild.
     type: u64
   - name: members
+    description: >
+      All members of guild. Might not available on start-up if the
+      `large` field is `true`.
     custom: decode_members
     t: UserId, Member
     type: hashmap
   - name: mfa_level
+    description: >
+      Lets you you know if guild requires 2-factor authentication for
+      administrators.
     type: u64
   - name: name
+    description: The guild's name.
     type: string
   - name: owner_id
+    description: Id of the guild's owner.
     type: UserId
   - name: presences
+    description: Presence statuses of members.
     custom: decode_emojis
     t: UserId, Presence
     type: hashmap
   - name: region
+    description: The region that the guild's voice servers are located in.
     type: string
   - name: roles
+    description: All roles a guild has.
     custom: decode_roles
     t: RoleId, Role
     type: hashmap
   - name: splash
+    description: >
+      If [InviteSplash] feature is enabled, this can point to splash image
+      URL displayed when someone opens invite URL.
+      
+        [InviteSplash]: enum.Feature.html#variant.InviteSplash
     optional: true
     type: string
   - name: verification_level
+    description: Determines the verification level.
     type: VerificationLevel
   - name: voice_states
+    description: Lets you know what voice channels user have joined.
     custom: decode_voice_states
     t: UserId, VoiceState
     type: hashmap
diff --git a/definitions/structs/guild_channel.yml b/definitions/structs/guild_channel.yml
index 6db4fb4..d3c8b73 100644
--- a/definitions/structs/guild_channel.yml
+++ b/definitions/structs/guild_channel.yml
@@ -1,33 +1,51 @@
 ---
 name: GuildChannel
-description: A guild's voice or text channel.
+description: >
+  Represents a guild's voice or text channel. Some methods are available
+  only for voice channels and some are only available for text channels.
 fields:
   - name: id
+    description: >
+      Channel's Id. Default channel shares the Id with the guild it is in.
     type: ChannelId
   - name: bitrate
+    description: Bitrate of channel. Only available for voice channels.
     optional: true
     type: u64
   - name: guild_id
+    description: Id of the guild the channel is located in.
     type: GuildId
   - name: kind
+    description: Type of the channel.
     type: ChannelType
   - name: last_message_id
+    description: >
+      The Id of last message sent. It lets client determine
+      if channel has unread messages.
     optional: true
     type: MessageId
   - name: last_pin_timestamp
+    description: Timestamp of the latest pinned message.
     optional: true
     type: string
   - name: name
+    description: >
+      Channel name. Voice and text channels have different
+      limitations for this.
     type: string
   - name: permission_overwrites
+    description: Permission overwrites for members and roles.
     array: true
     type: PermissionOverwrite
   - name: position
+    description: Position of a channel.
     type: i64
   - name: topic
+    description: Text channel topic.
     optional: true
     type: string
   - name: user_limit
+    description: Max amount of members allowed in a voice channel.
     optional: true
     type: u64
 decode: false
diff --git a/definitions/structs/guild_info.yml b/definitions/structs/guild_info.yml
index bf1002c..349f5bf 100644
--- a/definitions/structs/guild_info.yml
+++ b/definitions/structs/guild_info.yml
@@ -1,15 +1,20 @@
 ---
 name: GuildInfo
-description: Basic information about a server
+description: Basic information about a guild used for oauth.
 fields:
   - name: id
+    description: Id of the Guild. Can be used to calculate the creation date.
     type: GuildId
   - name: icon
+    description: The guild's icon.
     optional: true
     type: string
   - name: name
+    description: The guild's name.
     type: string
   - name: owner
+    description: True if you're the owner of the guild.
     type: bool
   - name: permissions
+    description: Permissions that you have in the guild.
     type: Permissions
diff --git a/definitions/structs/invite.yml b/definitions/structs/invite.yml
index c2f41d1..a848592 100644
--- a/definitions/structs/invite.yml
+++ b/definitions/structs/invite.yml
@@ -1,6 +1,7 @@
 ---
 name: Invite
-description: Information about an invite.
+description: >
+  Information about an invite URL. Can't be accessed if you're banned.
 fields:
   - name: code
     description: The unique code for the invite.
diff --git a/definitions/structs/member.yml b/definitions/structs/member.yml
index 9f80021..7eb2ece 100644
--- a/definitions/structs/member.yml
+++ b/definitions/structs/member.yml
@@ -1,18 +1,24 @@
 ---
 name: Member
-description: Information about a member of a server
+description: Represents information about a member of a guild.
 fields:
   - name: deaf
+    description: True if user isn't allowed to hear in voice channels.
     type: bool
   - name: joined_at
+    description: Timestamp representing the date when the member joined.
     type: string
   - name: mute
+    description: True if user isn't allowed to talk in voice channels.
     type: bool
   - name: nick
+    description: Optional nickname. Can't be longer than 32 characters.
     optional: true
     type: string
   - name: roles
+    description: Ids of roles that were given to the member.
     array: true
     type: RoleId
   - name: user
+    description: Attached User struct.
     type: User
diff --git a/definitions/structs/message.yml b/definitions/structs/message.yml
index 97c7536..ef9408f 100644
--- a/definitions/structs/message.yml
+++ b/definitions/structs/message.yml
@@ -3,43 +3,62 @@ name: Message
 description: "A representation of a message sent over a guild's text channel, a group, or a private channel."
 fields:
   - name: id
+    description: Message Id. Can be used to calculate the message creation date.
     type: MessageId
   - name: attachments
+    description: Array of attached files a message has.
     array: true
     type: Attachment
   - name: author
+    description: User that sent the message.
     type: User
   - name: channel_id
+    description: Channel to which the message was sent.
     type: ChannelId
   - name: content
+    description: Message's content.
     type: string
   - name: edited_timestamp
+    description: >
+      If the message was edited, this will show the last edit timestamp.
     optional: true
     type: string
   - name: embeds
+    description: Array of embeds a message has.
     array: true
     type: Embed
   - name: kind
+    description: >
+      Lets you differentiate system messages and regular messages.
     from: type
     type: MessageType
   - name: mention_everyone
+    description: >
+      Shows you whether this message actually mentions everyone or not.
     type: bool
   - name: mention_roles
+    description: Array of roles mentioned by the message.
     array: true
     type: RoleId
   - name: mentions
+    description: Array of users mentioned by the messages.
     array: true
     type: User
   - name: nonce
+    description: Non-repeating number used for ensuring message order.
     optional: true
     type: string
   - name: pinned
+    description: True if message is pinned.
     type: bool
   - name: reactions
+    description: Array of reactions performed on the message.
     array: true
     default: Vec::default()
     type: MessageReaction
   - name: timestamp
+    description: Initial message creation timestamp calculated from Id.
     type: string
   - name: tts
+    description: True if message was sent with /tts command.
     type: bool
diff --git a/definitions/structs/presence.yml b/definitions/structs/presence.yml
index ae216fa..1c3800d 100644
--- a/definitions/structs/presence.yml
+++ b/definitions/structs/presence.yml
@@ -1,21 +1,27 @@
 ---
 name: Presence
-description: A member's online status
+description: A set of settings each member of a guild has.
 fields:
   - name: game
+    description: A game's name that is displayed near user's name.
     optional: true
     type: Game
   - name: last_modified
+    description: Date of last presence change.
     optional: true
     type: u64
   - name: nick
+    description: Optional nickname. Can't be longer than 32 characters.
     optional: true
     type: string
   - name: status
+    description: Member's online status.
     type: OnlineStatus
   - name: user_id
+    description: Member's Id. Can be used to calculate account creation date.
     type: UserId
   - name: user
+    description: Attached User struct.
     optional: true
     type: User
 decode: false
diff --git a/definitions/structs/private_channel.yml b/definitions/structs/private_channel.yml
index 8aff7db..cd7a5a7 100644
--- a/definitions/structs/private_channel.yml
+++ b/definitions/structs/private_channel.yml
@@ -3,15 +3,24 @@ name: PrivateChannel
 description: A Direct Message text channel with another user.
 fields:
   - name: id
+    description: >
+      Private channel's Id. Can be used to calculate the first message's
+      creation date.
     type: ChannelId
   - name: last_message_id
+    description: >
+      The Id of last message sent. It lets client determine
+      if the channel has unread messages.
     optional: true
     type: MessageId
   - name: last_pin_timestamp
+    description: Timestamp of the latest pinned message.
     optional: true
     type: string
   - name: kind
+    description: Lets you differentiate between channel types.
     type: ChannelType
   - name: recipient
+    description: User that receives messages in this channel.
     type: User
 decode: false
diff --git a/definitions/structs/read_state.yml b/definitions/structs/read_state.yml
index ef580b6..b9c9ec0 100644
--- a/definitions/structs/read_state.yml
+++ b/definitions/structs/read_state.yml
@@ -3,13 +3,17 @@ name: ReadState
 description: "Summary of messages since last login"
 fields:
   - name: id
+    description: The channel's Id.
     type: ChannelId
   - name: last_message_id
+    description: The Id of the latest message sent to the channel.
     optional: true
     type: MessageId
   - name: last_pin_timestamp
+    description: The timestmap of the latest pinned message in the channel.
     optional: true
     type: string
   - name: mention_count
+    description: The amount of times you've been mentioned in the channel.
     default: '0'
     type: u64
diff --git a/definitions/structs/ready.yml b/definitions/structs/ready.yml
index 84107df..4d24c4c 100644
--- a/definitions/structs/ready.yml
+++ b/definitions/structs/ready.yml
@@ -1,6 +1,8 @@
 ---
 name: Ready
-description: An active group or private call. These are different from server voice channels.
+description: >
+  An active group or private call. These are different from guild voice
+  channels.
 fields:
   - name: analytics_token
     optional: true
diff --git a/definitions/structs/relationship.yml b/definitions/structs/relationship.yml
index 8d3cc17..23024e4 100644
--- a/definitions/structs/relationship.yml
+++ b/definitions/structs/relationship.yml
@@ -1,11 +1,14 @@
 ---
 name: Relationship
-description: "Information about a relationship that this user has with another user."
+description: Information about a relationship that a user has with another user.
 fields:
   - name: id
+    description: Id of the first relationship participant.
     type: UserId
   - name: kind
+    description: Type of the relationship such as blocked, friends etc.
     from: type
     type: RelationshipType
   - name: user
+    description: User struct of the second relationship participant.
     type: User
diff --git a/definitions/structs/role.yml b/definitions/structs/role.yml
index f4c3616..9bd94ef 100644
--- a/definitions/structs/role.yml
+++ b/definitions/structs/role.yml
@@ -1,8 +1,15 @@
 ---
 name: Role
-description: "Information about a role within a guild. A role represents a set of permissions, and can be attached to one or multiple users. A role has various miscellaneous configurations, such as being assigned a colour. Roles are unique per guild and do not cross over to other guilds in any way, and can have channel-specific permission overrides in addition to guild-level permissions."
+description: >
+  Information about a role within a guild. A role represents a set of
+  permissions, and can be attached to one or multiple users. A role has
+  various miscellaneous configurations, such as being assigned a colour.
+  Roles are unique per guild and do not cross over to other guilds in any way,
+  and can have channel-specific permission overrides in addition to guild-level
+  permissions.
 fields:
   - name: id
+    description: The Id of the role. Can be used to calculate its creation date.
     type: RoleId
   - name: colour
     from: color
@@ -24,6 +31,7 @@ fields:
       a role is mentioned with this set to true."
     type: bool
   - name: name
+    description: The name of the role.
     type: string
   - name: permissions
     description: "A set of permissions that the role has been assigned. See the
diff --git a/definitions/structs/user.yml b/definitions/structs/user.yml
index d157ec4..297072e 100644
--- a/definitions/structs/user.yml
+++ b/definitions/structs/user.yml
@@ -1,17 +1,28 @@
 ---
 name: User
-description: Information about a user
+description: Information about a user.
 fields:
   - name: id
+    description: >
+      The unique Id of the user. Can be used to calculate the account's
+      creation date.
     type: UserId
   - name: avatar
+    description: Optional avatar hash.
     optional: true
     type: string
   - name: bot
+    description: Lets you know if the account is a bot or not.
     default: 'false'
     type: bool
   - name: discriminator
+    description: >
+      The account's discriminator. The name + discriminator pair is
+      always unique.
     type: string
   - name: name
+    description: >
+      The account's username. Changing username will trigger a
+      discriminator change if the pair is not unique.
     from: username
     type: string
diff --git a/src/client/context.rs b/src/client/context.rs
index b452c0c..d5068c3 100644
--- a/src/client/context.rs
+++ b/src/client/context.rs
@@ -243,6 +243,9 @@ impl Context {
     /// simple method to read an image and encode it into base64, if you are
     /// reading from the filesystem.
     ///
+    /// The name of the emoji must be at least 2 characters long and can only
+    /// contain alphanumeric characters and underscores.
+    ///
     /// **Note**: Requires the [Manage Emojis] permission.
     ///
     /// # Examples
@@ -1527,6 +1530,8 @@ impl Context {
     /// Use [`reset_presence`] to clear the current game, or [`set_presence`]
     /// for more fine-grained control.
     ///
+    /// **Note**: Maximum length is 128.
+    ///
     /// [`GameType`]: ../model/enum.GameType.html
     /// [`Online`]: ../model/enum.OnlineStatus.html#variant.Online
     /// [`OnlineStatus`]: ../model/enum.OnlineStatus.html
diff --git a/src/model/gateway.rs b/src/model/gateway.rs
index 93c779b..0b64e24 100644
--- a/src/model/gateway.rs
+++ b/src/model/gateway.rs
@@ -3,7 +3,9 @@ use super::*;
 use ::internal::prelude::*;
 
 impl Game {
-    /// Creates a `Game` struct that appears as a `**Playing** <name>` status.
+    /// Creates a `Game` struct that appears as a `Playing <name>` status.
+    ///
+    /// **Note**: Maximum `name` length is 128.
     #[cfg(feature="methods")]
     pub fn playing(name: &str) -> Game {
         Game {
@@ -13,7 +15,9 @@ impl Game {
         }
     }
 
-    /// Creates a `Game` struct that appears as a `**Streaming** <name>` status.
+    /// Creates a `Game` struct that appears as a `Streaming <name>` status.
+    ///
+    /// **Note**: Maximum `name` length is 128.
     #[cfg(feature="methods")]
     pub fn streaming(name: &str, url: &str) -> Game {
         Game {
diff --git a/src/model/guild.rs b/src/model/guild.rs
index b1733b1..2b5fbee 100644
--- a/src/model/guild.rs
+++ b/src/model/guild.rs
@@ -193,7 +193,7 @@ impl Guild {
     ///
     /// # Examples
     ///
-    /// Ban a member for 4 days:
+    /// Ban a member and remove all messages they've sent in the last 4 days:
     ///
     /// ```rust,ignore
     /// // assumes a `user` and `guild` have already been bound
diff --git a/src/utils/builder/create_embed.rs b/src/utils/builder/create_embed.rs
index 369784f..f9b7dcf 100644
--- a/src/utils/builder/create_embed.rs
+++ b/src/utils/builder/create_embed.rs
@@ -67,6 +67,8 @@ impl CreateEmbed {
     }
 
     /// Set the description of the embed.
+    ///
+    /// **Note**: This can't be longer than 2048 characters.
     pub fn description(mut self, description: &str) -> Self {
         self.0.insert("description".to_owned(), Value::String(description.to_owned()));
 
@@ -79,6 +81,9 @@ impl CreateEmbed {
     /// Refer to the documentation for [`CreateEmbedField`] for more
     /// information.
     ///
+    /// **Note**: Maximum amount of characters you can put is 256 in a field
+    /// name and 1024 in a field value and a field is inline by default.
+    ///
     /// [`CreateEmbedField`]: struct.CreateEmbedField.html
     pub fn field<F>(mut self, f: F) -> Self
         where F: FnOnce(CreateEmbedField) -> CreateEmbedField {
@@ -229,17 +234,17 @@ impl Default for CreateEmbedAuthor {
 pub struct CreateEmbedField(pub ObjectBuilder);
 
 impl CreateEmbedField {
-    /// Set whether the field is inlined.
+    /// Set whether the field is inlined. Set to true by default.
     pub fn inline(self, inline: bool) -> Self {
         CreateEmbedField(self.0.insert("inline", inline))
     }
 
-    /// Set the field's name.
+    /// Set the field's name. It can't be longer than 256 characters.
     pub fn name(self, name: &str) -> Self {
         CreateEmbedField(self.0.insert("name", name))
     }
 
-    /// Set the field's value.
+    /// Set the field's value. It can't be longer than 1024 characters.
     pub fn value(self, value: &str) -> Self {
         CreateEmbedField(self.0.insert("value", value))
     }