Cleanup YAML definition layouts

39 files changed, 176 insertions, 144 deletions

diff --git a/definitions/structs/affected_component.yml b/definitions/structs/affected_component.yml
index 00c4ca9..d5b8be3 100644
--- a/definitions/structs/affected_component.yml
+++ b/definitions/structs/affected_component.yml
@@ -3,6 +3,7 @@ name: AffectedComponent
 description: >
   A component that was affected during a service incident.
 
+
   This is pulled from the Discord status page.
 fields:
   - name: name
diff --git a/definitions/structs/application_info.yml b/definitions/structs/application_info.yml
index 172a511..581aca5 100644
--- a/definitions/structs/application_info.yml
+++ b/definitions/structs/application_info.yml
@@ -1,56 +1,65 @@
 ---
 name: ApplicationInfo
-description: "Information about a user's application. An application does not
-  necessarily have an associated bot user."
+description: >
+  Information about a user's application. An application does not necessarily
+  have an associated bot user.
 fields:
   - name: bot
-    description: "The bot user associated with this application. See
-      [BotApplication](./struct.BotApplication.html) for more information."
+    description: >
+      The bot user associated with this application. See [BotApplication] for
+      more information.
+
+        [BotApplication]: struct.BotApplication.html
     optional: true
     type: BotApplication
   - name: bot_public
     default: true
-    description: "Whether or not the bot is public. If a bot is public, anyone
-      may invite it to their [Guild](./struct.Guild.html). While a bot is
-      private, only the owner may invite it to a guild."
+    description: >
+      Whether or not the bot is public. If a bot is public, anyone may invite it
+      to their [Guild]. While a bot is private, only the owner may add it to a
+      guild.
+
+        [Guild]: struct.Guild.html
     type: bool
   - name: bot_require_code_grant
-    description: "Whether or not the bot requires an OAuth2 code grant."
+    description: Whether or not the bot requires an OAuth2 code grant.
     type: bool
   - name: description
-    description: "A description of the application, assigned by the application
-      owner."
+    description: >
+      A description of the application, assigned by the application owner.
     type: string
   - name: flags
-    description: "A set of bitflags assigned to the application, which represent
-      gated feature flags that have been enabled for the application's bot user.
+    description: >
+      A set of bitflags assigned to the application, which represent gated
+      feature flags that have been enabled for the application's bot user.
 
       If the application does not have a bot user, then bitflags are not
-      present."
+      present.
     optional: true
     type: u64
   - name: icon
-    description: "A hash pointing to the application's icon. This is not
-      necessarily equivilant to the bot user's avatar. If there is no icon
-      assigned, then this is None."
+    description: >
+      A hash pointing to the application's icon. This is not necessarily
+      equivilant to the bot user's avatar. If there is no icon assigned, then
+      this is None.
     optional: true
     type: string
   - name: id
-    description: "The numeric id of the application."
+    description: The numeric id of the application.
     type: UserId
   - name: name
-    description: "The name assigned to the application by the application
-      owner."
+    description: The name assigned to the application by the application owner.
     type: string
   - name: redirect_uris
     array: true
-    description: "A list of redirect URIs assigned to the application."
+    description: A list of redirect URIs assigned to the application.
     type: string
   - name: rpc_origins
     array: true
-    description: "A list of RPC Origins asigned to the application."
+    description: A list of RPC Origins asigned to the application.
     type: string
   - name: secret
-    description: "The given secret to the application. Note that this is not
-      equivilant to an application's bot user's token."
+    description: >
+      The given secret to the application. Note that this is not equivilant to
+      an application's bot user's token.
     type: string
diff --git a/definitions/structs/attachment.yml b/definitions/structs/attachment.yml
index 08c097e..675205e 100644
--- a/definitions/structs/attachment.yml
+++ b/definitions/structs/attachment.yml
@@ -1,34 +1,34 @@
 ---
 name: Attachment
 description: >
-  A file uploaded with a message. Not to be confused with [embed][`Embed`]s.
+  A file uploaded with a message. Not to be confused with [`Embed`]s.
 
-
-  [`Embed`]: struct.Embed.html
+    [`Embed`]: struct.Embed.html
 fields:
   - name: id
-    description: "The unique ID given to this attachment."
+    description: The unique ID given to this attachment.
     type: string
   - name: filename
-    description: "The filename of the file that was uploaded. This is equivilant
-      to what the uploader had their file named."
+    description: >
+      The filename of the file that was uploaded. This is equivilant to what the
+      uploader had their file named.
     type: string
   - name: height
-    description: "If the attachment is an image, then the height of the image is
-      provided."
+    description: >
+      If the attachment is an image, then the height of the image is provided.
     optional: true
     type: u64
   - name: proxy_url
-    description: "The proxy URL."
+    description: The proxy URL.
     type: string
   - name: size
-    description: "The size of the file in bytes."
+    description: The size of the file in bytes.
     type: u64
   - name: url
-    description: "The URL of the uploaded attachment."
+    description: The URL of the uploaded attachment.
     type: string
   - name: width
-    description: "If the attachment is an image, then the width of the image is
-      provided."
+    description: >
+      If the attachment is an image, then the width of the image is provided.
     optional: true
     type: u64
diff --git a/definitions/structs/bot_application.yml b/definitions/structs/bot_application.yml
index a1da049..8825230 100644
--- a/definitions/structs/bot_application.yml
+++ b/definitions/structs/bot_application.yml
@@ -3,30 +3,33 @@ name: BotApplication
 description: Information about an application with an application's bot user.
 fields:
   - name: id
-    description: "The Id of the bot user."
+    description: The Id of the bot user.
     type: UserId
   - name: avatar
-    description: "A hash of the avatar, if one is assigned. This can be used to
-      generate a full URL."
+    description: >
+      A hash of the avatar, if one is assigned. This can be used to generate a
+      full URL.
     optional: true
     type: string
   - name: bot
     default: 'false'
-    description: "Whether or not this is a bot."
+    description: Whether or not this is a bot.
     type: bool
   - name: discriminator
     custom: decode_discriminator
-    description: "The discriminator assigned to the user's username. While
-      discriminators are not unique, the username#discriminator combination is."
+    description: >
+      The discriminator assigned to the user's username. While discriminators
+      are not unique, the username#discriminator combination is.
     type: u16
   - name: name
-    description: "The username."
+    description: The username.
     from: username
     type: string
   - name: token
-    description: "The token used to login to the bot user.
+    description: >
+      The token used to login to the bot user.
 
 
       **Note**: Keep this information private, as untrusted users can use it to
-      log into your bot."
+      perform any action on a bot.
     type: string
diff --git a/definitions/structs/bot_gateway.yml b/definitions/structs/bot_gateway.yml
index c4ac183..418f79e 100644
--- a/definitions/structs/bot_gateway.yml
+++ b/definitions/structs/bot_gateway.yml
@@ -1,19 +1,17 @@
 ---
 name: BotGateway
-description: "A representation of the data retrieved from the bot gateway
-  endpoint.
+description: >
+  A representation of the data retrieved from the bot gateway endpoint.
 
 
   This is different from the [`Gateway`], as this includes the number of shards
   that is recommended for use by the bot and can only be used by bots.
 
-
-  [`Gateway`]: struct.Gateway.html"
+    [`Gateway`]: struct.Gateway.html
 fields:
   - name: shards
-    description: "The number of shards that is recommended to be used by the
-      bot."
+    description: The number of shards that is recommended to be used by the bot.
     type: u64
   - name: url
-    description: "The gateway to connect to."
+    description: The gateway to connect to.
     type: string
diff --git a/definitions/structs/call.yml b/definitions/structs/call.yml
index 3a8887a..b6d66a9 100644
--- a/definitions/structs/call.yml
+++ b/definitions/structs/call.yml
@@ -1,35 +1,35 @@
 ---
 name: Call
-description: "An active group or private call. These are different from
+description: >
+  An active group or private call. These are different from
   [voice channel][`ChannelType::Voice`]s in guilds.
 
-
-  [`ChannelType::Voice`]: enum.ChannelType.html#Voice.v"
+    [`ChannelType::Voice`]: enum.ChannelType.html#Voice.v
 fields:
   - name: channel_id
-    description: "The group or private channel that the call is associated
-      with."
+    description: The group or private channel that the call is associated with.
     type: ChannelId
   - name: message_id
-    description: "The Id of the [message][`Message`] denoting that the call is
-      active.
+    description: >
+      The Id of the [message][`Message`] denoting that the call is active.
 
-      [`Message`]: struct.Message.html"
+        [`Message`]: struct.Message.html
     type: MessageId
   - name: region
-    description: "The [region][`Region`] that the call is taking place in.
+    description: >
+      The [region][`Region`] that the call is taking place in.
 
-      [`Region`]: enum.Region.html"
+        [`Region`]: enum.Region.html
     type: string
   - name: ringing
-    description: "A list of users that are currently being ringed."
+    description: A list of users that are currently being ringed.
     array: true
     type: UserId
   - name: unavailable
-    description: "Whether the server hosting the call is unavailable."
+    description: Whether the server hosting the call is unavailable.
     type: bool
   - name: voice_states
     custom: decode_voice_states
-    description: "The users present in the call."
+    description: The users present in the call.
     t: UserId, VoiceState
     type: hashmap
diff --git a/definitions/structs/channel_override.yml b/definitions/structs/channel_override.yml
index d67726d..b6b22ac 100644
--- a/definitions/structs/channel_override.yml
+++ b/definitions/structs/channel_override.yml
@@ -1,17 +1,19 @@
 ---
 name: ChannelOverride
-description: "An override for a [channel][`Channel`].
+description: >
+  An override for a [channel][`Channel`].
 
-  [`Channel`]: enum.Channel.html"
+    [`Channel`]: enum.Channel.html
 fields:
   - name: channel_id
-    description: "The channel this override is for."
+    description: The channel this override is for.
     type: ChannelId
   - name: message_notifications
-    description: "The notification level to use for the channel."
+    description: The notification level to use for the channel.
     type: NotificationLevel
   - name: muted
-    description: "Whether or not the channel is muted; while this will not show
-      a notification indicator for the channel, it will continue to show when
-      the user is mentioned in it."
+    description: >
+      Whether or not the channel is muted; while this will not show a
+      notification indicator for the channel, it will continue to show when the
+      user is mentioned in it.
     type: bool
diff --git a/definitions/structs/current_user.yml b/definitions/structs/current_user.yml
index 948a828..090e1e3 100644
--- a/definitions/structs/current_user.yml
+++ b/definitions/structs/current_user.yml
@@ -1,6 +1,6 @@
 ---
 name: CurrentUser
-description: Information about the current user
+description: Information about the current user.
 fields:
   - name: id
     type: UserId
diff --git a/definitions/structs/embed.yml b/definitions/structs/embed.yml
index 76919dd..3ab4581 100644
--- a/definitions/structs/embed.yml
+++ b/definitions/structs/embed.yml
@@ -1,13 +1,12 @@
 ---
 name: Embed
 description: >
-  Represents a rich embed which allows using richer markdown,
-  multiple columns and more. This was heavily inspired by
-  [slack's attachments].
+  Represents a rich embed which allows using richer markdown, multiple fields
+  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.
+  or in a webhook.
 
 
   **Note**: Maximum amount of characters you can put is 256 in a field name,
diff --git a/definitions/structs/embed_author.yml b/definitions/structs/embed_author.yml
index b0c1fd2..7525c66 100644
--- a/definitions/structs/embed_author.yml
+++ b/definitions/structs/embed_author.yml
@@ -3,7 +3,6 @@ name: EmbedAuthor
 description: >
   An author object in an [`Embed`].
 
-
     [`Embed`]: struct.Embed.html
 fields:
   - name: icon_url
diff --git a/definitions/structs/embed_field.yml b/definitions/structs/embed_field.yml
index 5050936..19d1b17 100644
--- a/definitions/structs/embed_field.yml
+++ b/definitions/structs/embed_field.yml
@@ -3,7 +3,6 @@ name: EmbedField
 description: >
   A field object in an [`Embed`].
 
-
     [`Embed`]: struct.Embed.html
 fields:
   - name: inline
diff --git a/definitions/structs/embed_footer.yml b/definitions/structs/embed_footer.yml
index d840693..2901094 100644
--- a/definitions/structs/embed_footer.yml
+++ b/definitions/structs/embed_footer.yml
@@ -3,7 +3,6 @@ name: EmbedFooter
 description: >
   Footer information about an [`Embed`].
 
-
     [`Embed`]: struct.Embed.html
 fields:
   - name: icon_url
diff --git a/definitions/structs/embed_image.yml b/definitions/structs/embed_image.yml
index 19c406c..4bb77a0 100644
--- a/definitions/structs/embed_image.yml
+++ b/definitions/structs/embed_image.yml
@@ -3,7 +3,6 @@ name: EmbedImage
 description: >
   An image object in an [`Embed`].
 
-
     [`Embed`]: struct.Embed.html
 fields:
   - name: height
diff --git a/definitions/structs/embed_provider.yml b/definitions/structs/embed_provider.yml
index 754be37..0266265 100644
--- a/definitions/structs/embed_provider.yml
+++ b/definitions/structs/embed_provider.yml
@@ -1,6 +1,6 @@
 ---
 name: EmbedProvider
-description: The provider of an embed
+description: The provider of an embed.
 fields:
   - name: name
     description: The name of the provider.
diff --git a/definitions/structs/embed_thumbnail.yml b/definitions/structs/embed_thumbnail.yml
index 84597e4..2c0ddff 100644
--- a/definitions/structs/embed_thumbnail.yml
+++ b/definitions/structs/embed_thumbnail.yml
@@ -1,6 +1,6 @@
 ---
 name: EmbedThumbnail
-description: The dimensions and URL of an embed thumbnail
+description: The dimensions and URL of an embed thumbnail.
 fields:
   - name: height
     description: The height of the thumbnail in pixels.
diff --git a/definitions/structs/embed_video.yml b/definitions/structs/embed_video.yml
index 7296c85..6db8893 100644
--- a/definitions/structs/embed_video.yml
+++ b/definitions/structs/embed_video.yml
@@ -3,7 +3,6 @@ name: EmbedVideo
 description: >
   A video information object in an [`Embed`].
 
-
     [`Embed`]: struct.Embed.html
 fields:
   - name: height
diff --git a/definitions/structs/emoji.yml b/definitions/structs/emoji.yml
index 8a69cf1..bec6e4b 100644
--- a/definitions/structs/emoji.yml
+++ b/definitions/structs/emoji.yml
@@ -6,26 +6,29 @@ description: >
   it was created in.
 fields:
   - name: id
-    description: "The Id of the emoji."
+    description: The Id of the emoji.
     type: EmojiId
   - name: name
-    description: "The name of the emoji. It must be at least 2 characters
-      long and can only contain alphanumeric characters and underscores."
+    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
-      [integration][`Integration`] service.
+    description: >
+      Whether the emoji is managed via an [`Integration`] service.
 
-      [`Integration`]: struct.Integration.html"
+      [`Integration`]: struct.Integration.html
     type: bool
   - name: require_colons
-    description: "Whether the emoji name needs to be surrounded by colons in
-      order to be used by the client."
+    description: >
+      Whether the emoji name needs to be surrounded by colons in order to be
+      used by the client.
     type: bool
   - name: roles
     array: true
-    description: "A list of [`Role`]s that are allowed to use the emoji. If
-      there are no roles specified, then usage is unrestricted.
+    description: >
+      A list of [`Role`]s that are allowed to use the emoji. If there are no
+      roles specified, then usage is unrestricted.
 
-      [`Role`]: struct.Role.html"
+      [`Role`]: struct.Role.html
     type: RoleId
diff --git a/definitions/structs/emoji_identifier.yml b/definitions/structs/emoji_identifier.yml
index 01d14dc..dab116f 100644
--- a/definitions/structs/emoji_identifier.yml
+++ b/definitions/structs/emoji_identifier.yml
@@ -3,9 +3,10 @@ name: EmojiIdentifier
 description: Version of emoji struct used only when Id and name are known.
 fields:
   - name: id
-    description: "The Id of the emoji."
+    description: The Id of the emoji.
     type: EmojiId
   - name: name
-    description: "The name of the emoji. It must be at least 2 characters
-      long and can only contain alphanumeric characters and underscores."
+    description: >
+      The name of the emoji. It must be at least 2 characters long and can only
+      contain alphanumeric characters and underscores.
     type: string
diff --git a/definitions/structs/friend_source_flags.yml b/definitions/structs/friend_source_flags.yml
index 902d158..f40b16e 100644
--- a/definitions/structs/friend_source_flags.yml
+++ b/definitions/structs/friend_source_flags.yml
@@ -1,6 +1,6 @@
 ---
 name: FriendSourceFlags
-description: "Flags about who may or may not add the current user as a friend."
+description: Flags about who may or may not add the current user as a friend.
 fields:
   - name: all
     default: 'false'
diff --git a/definitions/structs/gateway.yml b/definitions/structs/gateway.yml
index a2abc5e..c13ca9d 100644
--- a/definitions/structs/gateway.yml
+++ b/definitions/structs/gateway.yml
@@ -1,13 +1,13 @@
 ---
 name: Gateway
-description: "A representation of the data retrieved from the gateway endpoint.
+description: >
+  A representation of the data retrieved from the gateway endpoint.
 
 
   For the bot-specific gateway, refer to [`BotGateway`].
 
-
-  [`BotGateway`]: struct.BotGateway.html"
+    [`BotGateway`]: struct.BotGateway.html
 fields:
   - name: url
-    description: "The gateway to connect to."
+    description: The gateway to connect to.
     type: string
diff --git a/definitions/structs/guild.yml b/definitions/structs/guild.yml
index 35104b3..f5dceda 100644
--- a/definitions/structs/guild.yml
+++ b/definitions/structs/guild.yml
@@ -1,7 +1,6 @@
 ---
 name: Guild
-description: >
-  Live information about a Discord guild such as channels, emojis, etc.
+description: 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.
@@ -51,7 +50,9 @@ fields:
   - name: large
     description: >
       Set to true if guild has a lot of users.
-      It means that guild members aren't sent on ready event.
+
+
+      True indicates that offline guild members aren't initially sent.
     type: bool
   - name: member_count
     description: >
@@ -59,15 +60,15 @@ fields:
     type: u64
   - name: members
     description: >
-      All members of guild. Might not available on start-up if the
-      `large` field is `true`.
+      Members of the guild. Members might not all be 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.
+      Indicator if guild requires 2-factor authentication for roles with certain
+      permissions.
     type: u64
   - name: name
     description: The guild's name.
@@ -92,7 +93,7 @@ fields:
     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
diff --git a/definitions/structs/guild_prune.yml b/definitions/structs/guild_prune.yml
index d5467bd..29990ef 100644
--- a/definitions/structs/guild_prune.yml
+++ b/definitions/structs/guild_prune.yml
@@ -1,6 +1,8 @@
 ---
 name: GuildPrune
-description: Representation of the number of members that would be pruned by a guild prune operation.
+description: >
+  Representation of the number of members that would be pruned by a guild prune
+  operation.
 fields:
   - name: pruned
     type: u64
diff --git a/definitions/structs/incident.yml b/definitions/structs/incident.yml
index f410a08..03513d1 100644
--- a/definitions/structs/incident.yml
+++ b/definitions/structs/incident.yml
@@ -1,6 +1,10 @@
 ---
 name: Incident
-description: "An incident retrieved from the Discord status page. This is not necessarily a representation of an ongoing incident."
+description: >
+  An incident retrieved from the Discord status page.
+
+
+  This is not necessarily a representation of an ongoing incident.
 fields:
   - name: created_at
     type: string
diff --git a/definitions/structs/incident_update.yml b/definitions/structs/incident_update.yml
index 2b9362d..dc97bc3 100644
--- a/definitions/structs/incident_update.yml
+++ b/definitions/structs/incident_update.yml
@@ -1,6 +1,11 @@
 ---
 name: IncidentUpdate
-description: "An update to an incident from the Discord status page. This will typically state what new information has been discovered about an incident."
+description: >
+  An update to an incident from the Discord status page.
+
+
+  This will typically state what new information has been discovered about an
+  incident.
 fields:
   - name: affected_components
     array: true
diff --git a/definitions/structs/invite.yml b/definitions/structs/invite.yml
index a848592..45beac3 100644
--- a/definitions/structs/invite.yml
+++ b/definitions/structs/invite.yml
@@ -1,7 +1,8 @@
 ---
 name: Invite
 description: >
-  Information about an invite URL. Can't be accessed if you're banned.
+  Information about an invite URL. Can't be accessed if the current user is
+  banned.
 fields:
   - name: code
     description: The unique code for the invite.
diff --git a/definitions/structs/invite_guild.yml b/definitions/structs/invite_guild.yml
index ef9c797..79ec067 100644
--- a/definitions/structs/invite_guild.yml
+++ b/definitions/structs/invite_guild.yml
@@ -1,6 +1,6 @@
 ---
 name: InviteGuild
-description: "A minimal amount of information about an invite's guild."
+description: A minimal amount of information about an invite's guild.
 fields:
   - name: id
     type: GuildId
diff --git a/definitions/structs/maintenance.yml b/definitions/structs/maintenance.yml
index a34afbe..9a34dbb 100644
--- a/definitions/structs/maintenance.yml
+++ b/definitions/structs/maintenance.yml
@@ -1,6 +1,8 @@
 ---
 name: Maintenance
-description: "A Discord status maintenance message. This can be either for active maintenances or for scheduled maintenances."
+description: >
+  A Discord status maintenance message. This can be either for active
+  maintenances or for scheduled maintenances.
 fields:
   - name: description
     type: string
diff --git a/definitions/structs/message.yml b/definitions/structs/message.yml
index ef9408f..2cd82a3 100644
--- a/definitions/structs/message.yml
+++ b/definitions/structs/message.yml
@@ -1,6 +1,8 @@
 ---
 name: Message
-description: "A representation of a message sent over a guild's text channel, a group, or a private channel."
+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.
@@ -28,8 +30,7 @@ fields:
     array: true
     type: Embed
   - name: kind
-    description: >
-      Lets you differentiate system messages and regular messages.
+    description: Lets you differentiate system messages and regular messages.
     from: type
     type: MessageType
   - name: mention_everyone
diff --git a/definitions/structs/private_channel.yml b/definitions/structs/private_channel.yml
index cd7a5a7..c369a34 100644
--- a/definitions/structs/private_channel.yml
+++ b/definitions/structs/private_channel.yml
@@ -9,8 +9,8 @@ fields:
     type: ChannelId
   - name: last_message_id
     description: >
-      The Id of last message sent. It lets client determine
-      if the channel has unread messages.
+      The Id of last message sent. It lets client determine if the channel has
+      unread messages.
     optional: true
     type: MessageId
   - name: last_pin_timestamp
diff --git a/definitions/structs/reaction.yml b/definitions/structs/reaction.yml
index 8ea32bb..d04388e 100644
--- a/definitions/structs/reaction.yml
+++ b/definitions/structs/reaction.yml
@@ -3,7 +3,6 @@ name: Reaction
 description: >
   An [`Emoji`] reaction to a [`Message`].
 
-
     [`Emoji`]: struct.Emoji.html
     [`Message`]: struct.Message.html
 fields:
diff --git a/definitions/structs/read_state.yml b/definitions/structs/read_state.yml
index b9c9ec0..b11b35b 100644
--- a/definitions/structs/read_state.yml
+++ b/definitions/structs/read_state.yml
@@ -1,6 +1,6 @@
 ---
 name: ReadState
-description: "Summary of messages since last login"
+description: Summary of messages since last login.
 fields:
   - name: id
     description: The channel's Id.
diff --git a/definitions/structs/ready.yml b/definitions/structs/ready.yml
index 4d24c4c..62f08bf 100644
--- a/definitions/structs/ready.yml
+++ b/definitions/structs/ready.yml
@@ -21,8 +21,9 @@ fields:
   - name: notes
     custom: decode_notes
     default: HashMap::default()
-    description: "The shard info for this session; the shard is used and the
-      total number of shards."
+    description: >
+      The shard info for this session; the shard is used and the total number of
+      shards.
     t: UserId, String
     type: hashmap
   - name: presences
@@ -50,7 +51,7 @@ fields:
     type: '[u8; 2]'
   - name: trace
     array: true
-    description: "The trace of guilds involved in this connection."
+    description: The trace of guilds involved in this connection.
     from: _trace
     optional: true
     type: string
diff --git a/definitions/structs/role.yml b/definitions/structs/role.yml
index 9bd94ef..62f8594 100644
--- a/definitions/structs/role.yml
+++ b/definitions/structs/role.yml
@@ -18,28 +18,34 @@ fields:
       representation of the inner value.
     type: Colour
   - name: hoist
-    description: "Whether the role is pinned above lesser roles, causing members
-      in the role to be seen above others."
+    description: >
+      Whether the role is pinned above lesser roles, causing members in the role
+      to be seen above others.
     type: bool
   - name: managed
-    description: "Whether the role is managed by an integration service."
+    description: Whether the role is managed by an integration service.
     type: bool
   - name: mentionable
     default: false
-    description: "Whether the role can be mentioned, similar to mentioning a
-      specific member or @everyone. Only members of the role will be notified if
-      a role is mentioned with this set to true."
+    description: >
+      Whether the role can be mentioned, similar to mentioning a specific member
+      or @everyone. Only members of the role will be notified if 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
-      `permissions` module for more information."
+    description: >
+      A set of permissions that the role has been assigned. See the
+      [`permissions`] module for more information.
+
+        [`permissions`]: permissions/index.html
     type: Permissions
   - name: position
-    description: "The role's position in the position list. Roles above another
-      are considered higher in the role hierarchy in most situations.
+    description: >
+      The role's position in the position list. Roles above another are
+      considered higher in the role hierarchy in most situations.
 
-      The @everyone role is always position -1 or 0."
+      The @everyone role is usually either position `-1` or `0`.
     type: i64
diff --git a/definitions/structs/tutorial.yml b/definitions/structs/tutorial.yml
index 93fe9dd..f7f6c2e 100644
--- a/definitions/structs/tutorial.yml
+++ b/definitions/structs/tutorial.yml
@@ -1,6 +1,6 @@
 ---
 name: Tutorial
-description: "The current user's progress through the Discord tutorial"
+description: The current user's progress through the Discord tutorial.
 fields:
   - name: indicators_confirmed
     array: true
diff --git a/definitions/structs/user_connection.yml b/definitions/structs/user_connection.yml
index 5503820..6c96e34 100644
--- a/definitions/structs/user_connection.yml
+++ b/definitions/structs/user_connection.yml
@@ -3,6 +3,7 @@ name: UserConnection
 description: >
   A user's connection.
 
+
   **Note**: This is not in any way related to a WebSocket connection.
 fields:
   - name: id
diff --git a/definitions/structs/user_guild_settings.yml b/definitions/structs/user_guild_settings.yml
index b264074..df0da07 100644
--- a/definitions/structs/user_guild_settings.yml
+++ b/definitions/structs/user_guild_settings.yml
@@ -1,6 +1,6 @@
 ---
 name: UserGuildSettings
-description: "Settings about a guild in regards to notification configuration"
+description: Settings about a guild in regards to notification configuration
 fields:
   - name: channel_overrides
     array: true
diff --git a/definitions/structs/user_settings.yml b/definitions/structs/user_settings.yml
index 308ab11..c99c89c 100644
--- a/definitions/structs/user_settings.yml
+++ b/definitions/structs/user_settings.yml
@@ -1,6 +1,6 @@
 ---
 name: UserSettings
-description: "User settings usually used to influence client behavior"
+description: User settings usually used to influence client behavior.
 fields:
   - name: convert_emoticons
     type: bool
diff --git a/definitions/structs/voice_state.yml b/definitions/structs/voice_state.yml
index f51d224..30dd151 100644
--- a/definitions/structs/voice_state.yml
+++ b/definitions/structs/voice_state.yml
@@ -1,6 +1,6 @@
 ---
 name: VoiceState
-description: "A member's state within a voice channel"
+description: A member's state within a voice channel.
 fields:
   - name: channel_id
     optional: true
diff --git a/definitions/structs/webhook.yml b/definitions/structs/webhook.yml
index 54e25fc..a33c754 100644
--- a/definitions/structs/webhook.yml
+++ b/definitions/structs/webhook.yml
@@ -17,14 +17,12 @@ fields:
     description: >
       The Id of the [channel][`GuildChannel`] that owns the webhook.
 
-
         [`GuildChannel`]: struct.GuildChannel.html
     type: ChannelId
   - name: guild_id
     description: >
       The Id of the [`Guild`] that owns the webhook.
 
-
         [`Guild`]: struct.Guild.html
     optional: true
     type: GuildId