From 54135875420aa62333f4eea1fd7a074f161463d1 Mon Sep 17 00:00:00 2001
From: Still Hsu <341464@gmail.com>
Date: Sun, 21 Oct 2018 17:56:48 +0800
Subject: [PATCH] Streamline docs for Attachment + This commit also adds
 further explanation for why Embeds and Attachments are read-only collections

---
 src/Discord.Net.Core/Entities/Messages/IAttachment.cs |  2 +-
 src/Discord.Net.Core/Entities/Messages/IMessage.cs    | 10 ++++++++++
 src/Discord.Net.Rest/Entities/Messages/Attachment.cs  |  4 +---
 3 files changed, 12 insertions(+), 4 deletions(-)

diff --git a/src/Discord.Net.Core/Entities/Messages/IAttachment.cs b/src/Discord.Net.Core/Entities/Messages/IAttachment.cs
index 13b2cf48a..655777998 100644
--- a/src/Discord.Net.Core/Entities/Messages/IAttachment.cs
+++ b/src/Discord.Net.Core/Entities/Messages/IAttachment.cs
@@ -1,7 +1,7 @@
 namespace Discord
 {
     /// <summary>
-    ///     Represents a Discord attachment.
+    ///     Represents a message attachment found in a <see cref="IUserMessage"/>.
     /// </summary>
     public interface IAttachment
     {
diff --git a/src/Discord.Net.Core/Entities/Messages/IMessage.cs b/src/Discord.Net.Core/Entities/Messages/IMessage.cs
index 96d5c483b..b5c6a52a0 100644
--- a/src/Discord.Net.Core/Entities/Messages/IMessage.cs
+++ b/src/Discord.Net.Core/Entities/Messages/IMessage.cs
@@ -64,6 +64,11 @@ namespace Discord
         /// <summary>
         ///     Gets all attachments included in this message.
         /// </summary>
+        /// <remarks>
+        ///     This property gets a read-only collection of attachments associated with this message. Depending on the
+        ///     user's end-client, a sent message may contain one or more attachments. For example, mobile users may
+        ///     attach more than one file in their message, while the desktop client only allows for one.
+        /// </remarks>
         /// <returns>
         ///     A read-only collection of attachments.
         /// </returns>
@@ -71,6 +76,11 @@ namespace Discord
         /// <summary>
         ///     Gets all embeds included in this message.
         /// </summary>
+        /// <remarks>
+        /// </remarks>
+        ///     This property gets a read-only collection of embeds associated with this message. Depending on the
+        ///     message, a sent message may contain one or more embeds. This is usually true when multiple link previews
+        ///     are generated; however, only one <see cref="EmbedType.Rich"/> <see cref="Embed"/> can be featured.
         /// <returns>
         ///     A read-only collection of embed objects.
         /// </returns>
diff --git a/src/Discord.Net.Rest/Entities/Messages/Attachment.cs b/src/Discord.Net.Rest/Entities/Messages/Attachment.cs
index a2c7b9cf7..abe049180 100644
--- a/src/Discord.Net.Rest/Entities/Messages/Attachment.cs
+++ b/src/Discord.Net.Rest/Entities/Messages/Attachment.cs
@@ -3,9 +3,7 @@ using Model = Discord.API.Attachment;
 
 namespace Discord
 {
-    /// <summary>
-    ///     An attachment file seen in a <see cref="IUserMessage"/>.
-    /// </summary>
+    /// <inheritdoc/>
     [DebuggerDisplay(@"{DebuggerDisplay,nq}")]
     public class Attachment : IAttachment
     {