docs: September 2019 Documentation Update (#1379)

* docs: adjust wording of ActivityType.Watching enum

Adjusts the xmldoc summary wording of the ActivityType.Watching enum to
fix a wording issue.

* Add D.NET Logo to Open Graph meta tags

* Update DescriptionGenerator
...And update color to suit the logo better

* Disable smooth scrolling due to user complaints

* Remove unnecessary spacing in sideaffix

* Update footer version

* Remove featherlight plugin

As it is unnecessary and can break image tags

* Adjust wordings regarding safe-handling of secrets

* Fix formatting for first bot token sample

* Add badges to homepage

* Minor wording fixes on terminal

* Update to higher quality PNG

* Add Discord.Net.Example in sln for build validation

* Clarify all instances of IAsnycEnumerable

* Clarify overridden props in SocketNewsChannel

* Add returns and params docs for SyncPermissionsAsync

* Remove/fix invalid XMLdoc strings

* Remove AppVeyor and add GitHub badge

Discord.Net.sln

@@ -36,7 +36,9 @@ Project("{9A19103F-16F7-4668-BE54-9A1E7A4F7556}") = "Discord.Net.Tests.Integrati
 EndProject
 Project("{2150E333-8FDC-42A3-9474-1A3956D46DE8}") = "Tests", "Tests", "{C7CF5621-7D36-433B-B337-5A2E3C101A71}"
 EndProject
-Project("{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}") = "Discord.Net.Analyzers.Tests", "test\Discord.Net.Analyzers.Tests\Discord.Net.Analyzers.Tests.csproj", "{FC67057C-E92F-4E1C-98BE-46F839C8AD71}"
+Project("{9A19103F-16F7-4668-BE54-9A1E7A4F7556}") = "Discord.Net.Analyzers.Tests", "test\Discord.Net.Analyzers.Tests\Discord.Net.Analyzers.Tests.csproj", "{FC67057C-E92F-4E1C-98BE-46F839C8AD71}"
+EndProject
+Project("{9A19103F-16F7-4668-BE54-9A1E7A4F7556}") = "Discord.Net.Examples", "src\Discord.Net.Examples\Discord.Net.Examples.csproj", "{47820065-3CFB-401C-ACEA-862BD564A404}"
 EndProject
 Global
 	GlobalSection(SolutionConfigurationPlatforms) = preSolution
@@ -204,6 +206,18 @@ Global
 		{FC67057C-E92F-4E1C-98BE-46F839C8AD71}.Release|x64.Build.0 = Release|Any CPU
 		{FC67057C-E92F-4E1C-98BE-46F839C8AD71}.Release|x86.ActiveCfg = Release|Any CPU
 		{FC67057C-E92F-4E1C-98BE-46F839C8AD71}.Release|x86.Build.0 = Release|Any CPU
+		{47820065-3CFB-401C-ACEA-862BD564A404}.Debug|Any CPU.ActiveCfg = Debug|Any CPU
+		{47820065-3CFB-401C-ACEA-862BD564A404}.Debug|Any CPU.Build.0 = Debug|Any CPU
+		{47820065-3CFB-401C-ACEA-862BD564A404}.Debug|x64.ActiveCfg = Debug|Any CPU
+		{47820065-3CFB-401C-ACEA-862BD564A404}.Debug|x64.Build.0 = Debug|Any CPU
+		{47820065-3CFB-401C-ACEA-862BD564A404}.Debug|x86.ActiveCfg = Debug|Any CPU
+		{47820065-3CFB-401C-ACEA-862BD564A404}.Debug|x86.Build.0 = Debug|Any CPU
+		{47820065-3CFB-401C-ACEA-862BD564A404}.Release|Any CPU.ActiveCfg = Release|Any CPU
+		{47820065-3CFB-401C-ACEA-862BD564A404}.Release|Any CPU.Build.0 = Release|Any CPU
+		{47820065-3CFB-401C-ACEA-862BD564A404}.Release|x64.ActiveCfg = Release|Any CPU
+		{47820065-3CFB-401C-ACEA-862BD564A404}.Release|x64.Build.0 = Release|Any CPU
+		{47820065-3CFB-401C-ACEA-862BD564A404}.Release|x86.ActiveCfg = Release|Any CPU
+		{47820065-3CFB-401C-ACEA-862BD564A404}.Release|x86.Build.0 = Release|Any CPU
 	EndGlobalSection
 	GlobalSection(SolutionProperties) = preSolution
 		HideSolutionNode = FALSE
@@ -221,6 +235,7 @@ Global
 		{DBF8B16E-5967-4480-8EDE-15D98A0DF0C4} = {C7CF5621-7D36-433B-B337-5A2E3C101A71}
 		{E169E15A-E82C-45BF-8C24-C2CADB7093AA} = {C7CF5621-7D36-433B-B337-5A2E3C101A71}
 		{FC67057C-E92F-4E1C-98BE-46F839C8AD71} = {C7CF5621-7D36-433B-B337-5A2E3C101A71}
+		{47820065-3CFB-401C-ACEA-862BD564A404} = {BB59D5B5-E7B0-4BF4-8F82-D14431B2799B}
 	EndGlobalSection
 	GlobalSection(ExtensibilityGlobals) = postSolution
 		SolutionGuid = {D2404771-EEC8-45F2-9D71-F3373F6C1495}

docs/_template/light-dark-theme/partials/head.tmpl.partial

@@ -5,9 +5,18 @@
   <meta http-equiv="X-UA-Compatible" content="IE=edge,chrome=1">
   <title>{{#title}}{{title}}{{/title}}{{^title}}{{>partials/title}}{{/title}} {{#_appTitle}}| {{_appTitle}} {{/_appTitle}}</title>
   <meta name="viewport" content="width=device-width">
-  <meta name="title" content="{{#title}}{{title}}{{/title}}{{^title}}{{>partials/title}}{{/title}} {{#_appTitle}}| {{_appTitle}} {{/_appTitle}}">
+  <meta property="og:title" content="{{#title}}{{title}}{{/title}}{{^title}}{{>partials/title}}{{/title}} {{#_appTitle}}| {{_appTitle}} {{/_appTitle}}">
+  {{#_description}}<meta property="og:description" content="{{_description}}">{{/_description}}
+  <meta property="og:locale" content="en-us">
+  <meta property="og:type" content="website">
+  <meta property="og:site_name" content="Discord.Net Docs">
+  <meta property="og:image" content="https://cdn.jsdelivr.net/gh/discord-net/Discord.Net/docs/marketing/logo/PackageLogo.png">
+  <meta property="og:image:alt" content="Discord.Net Logo">
+  <meta name="theme-color" content="#995EA7"/>
   <meta name="generator" content="docfx {{_docfxVersion}}">
-  {{#_description}}<meta name="description" content="{{_description}}">{{/_description}}
+  <meta property="docfx:navrel" content="{{_navRel}}">
+  <meta property="docfx:tocrel" content="{{_tocRel}}">
+  <meta id="docfx-style:rel" content="{{_rel}}">
   <link rel="preload" href="{{_rel}}styles/search-worker.js" as="script">
   <link rel="preload" href="{{_rel}}fonts/glyphicons-halflings-regular.woff2" as="font" type="font/woff2" crossorigin="anonymous">
   <link rel="shortcut icon" href="{{_rel}}{{{_appFaviconPath}}}{{^_appFaviconPath}}favicon.ico{{/_appFaviconPath}}">
@@ -18,10 +27,6 @@
   <link rel="stylesheet" href="{{_rel}}styles/material.css">
   <link rel="stylesheet" href="{{_rel}}styles/theme-switcher.css">
   <link href="https://cdn.rawgit.com/noelboss/featherlight/1.7.6/release/featherlight.min.css" type="text/css" rel="stylesheet" />
-  <meta name="theme-color" content="#99AAB5"/>
-  <meta property="docfx:navrel" content="{{_navRel}}">
-  <meta property="docfx:tocrel" content="{{_tocRel}}">
-  <meta id="docfx-style:rel" content="{{_rel}}">
   {{#_noindex}}<meta name="searchOption" content="noindex">{{/_noindex}}
   {{#_enableSearch}}<meta property="docfx:rel" content="{{_rel}}">{{/_enableSearch}}
   {{#_enableNewTab}}<meta property="docfx:newtab" content="true">{{/_enableNewTab}}

docs/_template/light-dark-theme/partials/scripts.tmpl.partial

@@ -3,8 +3,6 @@
 <script type="text/javascript" src="{{_rel}}styles/docfx.vendor.js"></script>
 <script type="text/javascript" src="{{_rel}}styles/docfx.js"></script>
 <script type="text/javascript" src="{{_rel}}styles/main.js"></script>
-<script type="text/javascript" src="https://cdn.rawgit.com/noelboss/featherlight/master/release/featherlight.min.js" charset="utf-8"></script>
-<script type="text/javascript" src="{{_rel}}styles/plugin-featherlight.js"></script>
 <script type="text/javascript" src="{{_rel}}styles/styleswitcher.js"></script>
 <script type="text/javascript" src="https://malsup.github.io/jquery.corner.js"></script>
 <script type="text/javascript" src="{{_rel}}styles/cornerify.js"></script>

docs/_template/light-dark-theme/styles/master.css

@@ -6,7 +6,6 @@ body {
     font-display: optional;
     height: 100%;
     font-size: 15px;
-    scroll-behavior: smooth;
 }
 
 code{
@@ -92,6 +91,10 @@ article.content h6{
     line-height: 140%;
 }
 
+.sideaffix > div.contribution {
+    margin-bottom: 0;
+}
+
 header .navbar {
     border-width: 0 0 0px;
     border-radius: 0;

docs/_template/light-dark-theme/styles/plugin-featherlight.js

@@ -1,37 +0,0 @@
-// MIT License
-
-// Copyright (c) 2017 Roel Fauconnier
-
-// Permission is hereby granted, free of charge, to any person obtaining a copy
-// of this software and associated documentation files (the "Software"), to deal
-// in the Software without restriction, including without limitation the rights
-// to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-// copies of the Software, and to permit persons to whom the Software is
-// furnished to do so, subject to the following conditions:
-
-// The above copyright notice and this permission notice shall be included in all
-// copies or substantial portions of the Software.
-
-// THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-// IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-// FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-// AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-// LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-// OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-// SOFTWARE.
-
-$(document).ready(function() {
-        //find all images, but not the logo, and add the lightbox
-        $('img').not('#logo').each(function(){
-            var $img = $(this);
-            var filename = $img.attr('src')
-            //add cursor
-            $img.css('cursor','zoom-in');
-            $img.css('cursor','-moz-zoom-in');
-            $img.css('cursor','-webkit-zoom-in');
-
-            //add featherlight
-            $img.attr('alt', filename);
-            $img.featherlight(filename);
-    });
-});

docs/docfx.json

@@ -35,7 +35,8 @@
         "**/images/**",
         "**/samples/**",
         "langwordMapping.yml",
-        "marketing/logo/SVG/**.svg",
+        "marketing/logo/**.svg",
+        "marketing/logo/**.png",
         "favicon.ico"
       ]
     }],
@@ -50,7 +51,7 @@
     "overwrite": "_overwrites/**/**.md",
     "globalMetadata": {
       "_appTitle": "Discord.Net Documentation",
-      "_appFooter": "Discord.Net (c) 2015-2019 2.0.1",
+      "_appFooter": "Discord.Net (c) 2015-2019 2.1.1",
       "_enableSearch": true,
       "_appLogoPath": "marketing/logo/SVG/Logomark Purple.svg",
       "_appFaviconPath":  "favicon.ico"

docs/guides/getting_started/first-bot.md

@@ -146,23 +146,6 @@ method with the application's "token."
 > Pay attention to what you are copying from the developer portal!
 > A token is not the same as the application's "client secret."
 
-> [!IMPORTANT]
-> Your bot's token can be used to gain total access to your bot, so
-> **do not** share this token with anyone else! You should store this
-> token in an external source if you plan on distributing
-> the source code for your bot.
->
-> In the following example, we retrieve the token from the environment
-> variable `DiscordToken`. Please note that this is *not* designed to
-> be used in a production environment, as the secrets are stored in
-> plain-text.
->
-> For information on how to set an environment variable, please see
-> instructions below,
->
-> * Windows: [How to Create Environment Variables Shortcut in Windows](https://www.tenforums.com/tutorials/121742-create-environment-variables-shortcut-windows.html)
-> * Linux: [How To Read and Set Environmental and Shell Variables on a Linux VPS](https://www.digitalocean.com/community/tutorials/how-to-read-and-set-environmental-and-shell-variables-on-a-linux-vps)
-> * macOS: [How do I set environment variables on OS X?](https://apple.stackexchange.com/questions/106778/how-do-i-set-environment-variables-on-os-x)
 
 We may now invoke the client's [StartAsync] method, which will
 start connection/reconnection logic. It is important to note that
@@ -175,6 +158,22 @@ Finally, we will want to block the async main method from returning
 when running the application. To do this, we can await an infinite delay
 or any other blocking method, such as reading from the console.
 
+> [!IMPORTANT]
+> Your bot's token can be used to gain total access to your bot, so
+> **do not** share this token with anyone else! You should store this
+> token in an external source if you plan on distributing
+> the source code for your bot.
+>
+> In the following example, we retrieve the token from a pre-defined
+> variable, which is **NOT** secure, especially if you plan on 
+> distributing the application in any shape or form.
+>
+> We recommend alternative storage such as 
+> [Environment Variables], an external configuration file, or a 
+> secrets manager for safe-handling of secrets.
+>
+> [Environment Variables]: https://en.wikipedia.org/wiki/Environment_variable
+
 The following lines can now be added:
 
 [!code-csharp[Create client](samples/first-bot/client.cs)]

docs/guides/getting_started/installing.md

@@ -78,7 +78,7 @@ published to our [MyGet feed]. See
 
 ### [Using dotnet CLI](#tab/dotnet-cli)
 
-1. Launch your terminal
+1. Launch a terminal of your choice
 2. Navigate to where your `*.csproj` is located
 3. Enter `dotnet add package Discord.Net`
 
@@ -90,7 +90,7 @@ In order to compile Discord.Net, you will need the following:
 
 ### Using Visual Studio
 
-* [Visual Studio 2017](https://www.visualstudio.com/)
+* [Visual Studio 2019](https://visualstudio.microsoft.com/)
 * [.NET Core SDK]
 
 The .NET Core and Docker workload is required during Visual Studio
@@ -109,7 +109,7 @@ When running any Discord.Net-powered bot on an older operating system
 you may encounter a @System.PlatformNotSupportedException upon
 connecting.
 
-You may resolve this by either targeting .NET Core 2.1 or later, or
+You may resolve this by either targeting .NET Core 2.1 or higher, or
 by installing one or more custom packages as listed below.
 
 #### [Targeting .NET Core 2.1](#tab/core2-1)
@@ -141,4 +141,4 @@ over the default ones.
 
 ***
 
-[.NET Core SDK]: https://www.microsoft.com/net/download/
+[.NET Core SDK]: https://dotnet.microsoft.com/download

docs/guides/getting_started/nightlies.md

@@ -53,7 +53,7 @@ adding the feed to your package source.
 
 ### [Using dotnet CLI](#tab/cli)
 
-1. Launch your terminal
+1. Launch a terminal of your choice
 2. Navigate to where your `*.csproj` is located
 3. Type `dotnet add package Discord.Net --source https://www.myget.org/F/discord-net/api/v3/index.json`
 

docs/guides/getting_started/samples/first-bot/client.cs

@@ -2,22 +2,22 @@ private DiscordSocketClient _client;
 
 public async Task MainAsync()
 {
-	_client = new DiscordSocketClient();
+    _client = new DiscordSocketClient();
 
-	_client.Log += Log;
-    
-    // You can assign your bot token to a string, and pass that in to connect.
-    // This however is insecure, particularly if you plan to have your code hosted in a repository.
+    _client.Log += Log;
+
+    //  You can assign your bot token to a string, and pass that in to connect.
+    //  This is, however, insecure, particularly if you plan to have your code hosted in a public repository.
     var token = "token";
-    
-    // Some alternative  options would be to keep your token in an Environment Variable or a standalone file.
+
+    // Some alternative options would be to keep your token in an Environment Variable or a standalone file.
     // var token = Environment.GetEnvironmentVariable("NameOfYourEnvironmentVariable");
     // var token = File.ReadAllText("token.txt");
     // var token = JsonConvert.DeserializeObject<AConfigurationClass>(File.ReadAllText("config.json")).Token;
 
-	await _client.LoginAsync(TokenType.Bot, token);
-	await _client.StartAsync();
+    await _client.LoginAsync(TokenType.Bot, token);
+    await _client.StartAsync();
 
-	// Block this task until the program is closed.
-	await Task.Delay(-1);
-}
+    // Block this task until the program is closed.
+    await Task.Delay(-1);
+}

docs/index.md

@@ -5,7 +5,13 @@ title: Home
 
 # Discord.Net Documentation
 
-<div class="big-logo logo-switcher" />
+<div class="big-logo logo-switcher"></div>
+
+[![GitHub](https://img.shields.io/github/last-commit/discord-net/discord.net?style=plastic)](https://github.com/discord-net/Discord.Net)
+[![NuGet](https://img.shields.io/nuget/vpre/Discord.Net.svg?maxAge=2592000?style=plastic)](https://www.nuget.org/packages/Discord.Net)
+[![MyGet](https://img.shields.io/myget/discord-net/vpre/Discord.Net.svg)](https://www.myget.org/feed/Packages/discord-net)
+[![Build Status](https://dev.azure.com/discord-net/Discord.Net/_apis/build/status/discord-net.Discord.Net?branchName=dev)](https://dev.azure.com/discord-net/Discord.Net/_build/latest?definitionId=1&branchName=dev)
+[![Discord](https://discordapp.com/api/guilds/81384788765712384/widget.png)](https://discord.gg/jkrBmQR)
 
 ## What is Discord.Net?
 
@@ -20,11 +26,3 @@ If this is your first time using Discord.Net, you should refer to the
 More experienced users might want to refer to the
 [API Documentation](xref:API.Docs) for a breakdown of the individual
 objects in the library.
-
-## Additional Resources
-
-- [Discord API Guild](https://discord.gg/discord-api) - Look for `#dotnet_discord-net`
-- [GitHub](https://github.com/RogueException/Discord.Net/)
-- [NuGet](https://www.nuget.org/packages/Discord.Net/)
-- [MyGet Feed](https://www.myget.org/feed/Packages/discord-net) - Add-ons and nightly builds
-- [AppVeyor CI](https://ci.appveyor.com/project/RogueException/discord-net) - Nightly builds via Continuous Integration

src/Discord.Net.Core/Entities/Activities/ActivityType.cs

@@ -18,7 +18,7 @@ namespace Discord
         /// </summary>
         Listening = 2,
         /// <summary>
-        ///     The user is watching a media.
+        ///     The user is watching some form of media.
         /// </summary>
         Watching = 3
     }

src/Discord.Net.Core/Entities/Channels/Direction.cs

@@ -1,14 +1,15 @@
 namespace Discord
 {
     /// <summary>
-     ///     Specifies the direction of where message(s) should be retrieved from.
+    ///     Specifies the direction of where message(s) should be retrieved from.
     /// </summary>
     /// <remarks>
     ///     This enum is used to specify the direction for retrieving messages.
     ///     <note type="important">
     ///         At the time of writing, <see cref="Around"/> is not yet implemented into 
-    ///         <see cref="IMessageChannel.GetMessagesAsync"/>. Attempting to use the method with <see cref="Around"/>
-    ///         as its direction will throw a <see cref="System.NotImplementedException"/>.
+    ///         <see cref="IMessageChannel.GetMessagesAsync(int, CacheMode, RequestOptions)"/>.
+    ///         Attempting to use the method with <see cref="Around"/> will throw
+    ///         a <see cref="System.NotImplementedException"/>.
     ///     </note>
     /// </remarks>
     public enum Direction

src/Discord.Net.Core/Entities/Channels/IChannel.cs

@@ -17,14 +17,24 @@ namespace Discord
         string Name { get; }
 
         /// <summary>
-        ///     Gets a collection of all users in this channel.
+        ///     Gets a collection of users that are able to view the channel or are currently in this channel.
         /// </summary>
+        /// <remarks>
+        ///     <note type="important">
+        ///         The returned collection is an asynchronous enumerable object; one must call 
+        ///         <see cref="AsyncEnumerableExtensions.FlattenAsync{T}"/> to access the individual messages as a
+        ///         collection.
+        ///     </note>
+        ///     This method will attempt to fetch all users that is able to view this channel or is currently in this channel.
+        ///     The library will attempt to split up the requests according to and <see cref="DiscordConfig.MaxUsersPerBatch"/>.
+        ///     In other words, if there are 3000 users, and the <see cref="Discord.DiscordConfig.MaxUsersPerBatch"/> constant
+        ///     is <c>1000</c>, the request will be split into 3 individual requests; thus returning 53individual asynchronous
+        ///     responses, hence the need of flattening.
+        /// </remarks>
         /// <param name="mode">The <see cref="CacheMode"/> that determines whether the object should be fetched from cache.</param>
         /// <param name="options">The options to be used when sending the request.</param>
         /// <returns>
-        ///     A paged collection containing a collection of users that can access this channel. Flattening the
-        ///     paginated response into a collection of users with 
-        ///     <see cref="AsyncEnumerableExtensions.FlattenAsync{T}"/> is required if you wish to access the users.
+        ///     Paged collection of users.
         /// </returns>
         IAsyncEnumerable<IReadOnlyCollection<IUser>> GetUsersAsync(CacheMode mode = CacheMode.AllowDownload, RequestOptions options = null);
 

src/Discord.Net.Core/Entities/Channels/IGuildChannel.cs

@@ -132,14 +132,16 @@ namespace Discord
         Task AddPermissionOverwriteAsync(IUser user, OverwritePermissions permissions, RequestOptions options = null);
 
         /// <summary>
-        ///     Gets a collection of users that are able to view the channel.
+        ///     Gets a collection of users that are able to view the channel or are currently in this channel.
         /// </summary>
+        /// <remarks>
+        ///     This method follows the same behavior as described in <see cref="IChannel.GetUsersAsync"/>.
+        ///     Please visit its documentation for more details on this method.
+        /// </remarks>
         /// <param name="mode">The <see cref="CacheMode" /> that determines whether the object should be fetched from cache.</param>
         /// <param name="options">The options to be used when sending the request.</param>
         /// <returns>
-        ///     A paged collection containing a collection of guild users that can access this channel. Flattening the
-        ///     paginated response into a collection of users with 
-        ///     <see cref="AsyncEnumerableExtensions.FlattenAsync{T}"/> is required if you wish to access the users.
+        ///     Paged collection of users.
         /// </returns>
         new IAsyncEnumerable<IReadOnlyCollection<IGuildUser>> GetUsersAsync(CacheMode mode = CacheMode.AllowDownload, RequestOptions options = null);
         /// <summary>

src/Discord.Net.Core/Entities/Channels/INestedChannel.cs

@@ -26,10 +26,14 @@ namespace Discord
         ///     representing the parent of this channel; <c>null</c> if none is set.
         /// </returns>
         Task<ICategoryChannel> GetCategoryAsync(CacheMode mode = CacheMode.AllowDownload, RequestOptions options = null);
-        
+
         /// <summary>
         ///     Syncs the permissions of this nested channel with its parent's.
         /// </summary>
+        /// <param name="options">The options to be used when sending the request.</param>
+        /// <returns>
+        ///     A task that represents the asynchronous operation for syncing channel permissions with its parent's.
+        /// </returns>
         Task SyncPermissionsAsync(RequestOptions options = null);
 
         /// <summary>

src/Discord.Net.Core/Entities/Guilds/IGuild.cs

@@ -586,11 +586,11 @@ namespace Discord
         /// <remarks>
         ///     This method requires you have an OAuth2 access token for the user, requested with the guilds.join scope, and that the bot have the MANAGE_INVITES permission in the guild.
         /// </remarks>
-        /// <param name="id">The snowflake identifier of the user.</param>
+        /// <param name="userId">The snowflake identifier of the user.</param>
         /// <param name="accessToken">The OAuth2 access token for the user, requested with the guilds.join scope.</param>
         /// <param name="func">The delegate containing the properties to be applied to the user upon being added to the guild.</param>
         /// <param name="options">The options to be used when sending the request.</param>
-        /// <returns>A guild user associated with the specified <paramref name="id" />; <c>null</c> if the user is already in the guild.</returns>
+        /// <returns>A guild user associated with the specified <paramref name="userId" />; <c>null</c> if the user is already in the guild.</returns>
         Task<IGuildUser> AddGuildUserAsync(ulong userId, string accessToken, Action<AddGuildUserProperties> func = null, RequestOptions options = null);
         /// <summary>
         ///     Gets a collection of all users in this guild.

src/Discord.Net.Core/Entities/Users/IGuildUser.cs

@@ -73,7 +73,7 @@ namespace Discord
         /// </summary>
         /// <example>
         ///     The following example checks if the current user has the ability to send a message with attachment in
-        ///     this channel; if so, uploads a file via <see cref="IMessageChannel.SendFileAsync"/>.
+        ///     this channel; if so, uploads a file via <see cref="IMessageChannel.SendFileAsync(string, string, bool, Embed, RequestOptions, bool)"/>.
         ///     <code language="cs">
         ///     if (currentUser?.GetPermissions(targetChannel)?.AttachFiles)
         ///         await targetChannel.SendFileAsync("fortnite.png");

src/Discord.Net.Core/Extensions/AsyncEnumerableExtensions.cs

@@ -5,6 +5,11 @@ using System.Threading.Tasks;
 namespace Discord
 {
     /// <summary> An extension class for squashing <see cref="IAsyncEnumerable{T}"/>. </summary>
+    /// <remarks>
+    ///     This set of extension methods will squash an <see cref="IAsyncEnumerable{T}"/> into a
+    ///     single <see cref="IEnumerable{T}"/>. This is often associated with requests that has a
+    ///     set limit when requesting.
+    /// </remarks>
     public static class AsyncEnumerableExtensions
     {
         /// <summary> Flattens the specified pages into one <see cref="IEnumerable{T}"/> asynchronously. </summary>

src/Discord.Net.Rest/Entities/Guilds/RestGuild.cs

@@ -294,7 +294,6 @@ namespace Discord.Rest
         /// <summary>
         ///     Gets a collection of all text channels in this guild.
         /// </summary>
-        /// <param name="mode">The <see cref="CacheMode"/> that determines whether the object should be fetched from cache.</param>
         /// <param name="options">The options to be used when sending the request.</param>
         /// <returns>
         ///     A task that represents the asynchronous get operation. The task result contains a read-only collection of

src/Discord.Net.WebSocket/Entities/Channels/SocketNewsChannel.cs

@@ -9,6 +9,11 @@ namespace Discord.WebSocket
     /// <summary>
     ///     Represents a WebSocket-based news channel in a guild that has the same properties as a <see cref="SocketTextChannel"/>.
     /// </summary>
+    /// <remarks>
+    ///     <note type="warning">
+    ///         Most of the properties and methods featured may not be supported due to the nature of the channel.
+    ///     </note>
+    /// </remarks>
     [DebuggerDisplay(@"{DebuggerDisplay,nq}")]
     public class SocketNewsChannel : SocketTextChannel
     {
@@ -22,31 +27,61 @@ namespace Discord.WebSocket
             entity.Update(state, model);
             return entity;
         }
+        /// <inheritdoc />
+        /// <remarks>
+        ///     <note type="important">
+        ///     This property is not supported by this type. Attempting to use this property will result in a <see cref="NotSupportedException"/>.
+        ///     </note>
+        /// </remarks>
         public override int SlowModeInterval
-        {
-            get { throw new NotSupportedException("News channels do not support Slow Mode."); }
-        }
+            => throw new NotSupportedException("News channels do not support Slow Mode.");
+        /// <inheritdoc />
+        /// <remarks>
+        ///     <note type="important">
+        ///     This method is not supported by this type. Attempting to use this method will result in a <see cref="NotSupportedException"/>.
+        ///     </note>
+        /// </remarks>
         public override Task AddPermissionOverwriteAsync(IRole role, OverwritePermissions permissions, RequestOptions options = null)
-        {
-            throw new NotSupportedException("News channels do not support Overwrite Permissions.");
-        }
+            => throw new NotSupportedException("News channels do not support Overwrite Permissions.");
+        /// <inheritdoc />
+        /// <remarks>
+        ///     <note type="important">
+        ///     This method is not supported by this type. Attempting to use this method will result in a <see cref="NotSupportedException"/>.
+        ///     </note>
+        /// </remarks>
         public override Task AddPermissionOverwriteAsync(IUser user, OverwritePermissions permissions, RequestOptions options = null)
-        {
-            throw new NotSupportedException("News channels do not support Overwrite Permissions.");
-        }
+            => throw new NotSupportedException("News channels do not support Overwrite Permissions.");
+        /// <inheritdoc />
+        /// <remarks>
+        ///     <note type="important">
+        ///     This property is not supported by this type. Attempting to use this property will result in a <see cref="NotSupportedException"/>.
+        ///     </note>
+        /// </remarks>
         public override IReadOnlyCollection<Overwrite> PermissionOverwrites
             => throw new NotSupportedException("News channels do not support Overwrite Permissions.");
+        /// <inheritdoc />
+        /// <remarks>
+        ///     <note type="important">
+        ///     This method is not supported by this type. Attempting to use this method will result in a <see cref="NotSupportedException"/>.
+        ///     </note>
+        /// </remarks>
         public override Task SyncPermissionsAsync(RequestOptions options = null)
-        {
-            throw new NotSupportedException("News channels do not support Overwrite Permissions.");
-        }
+            => throw new NotSupportedException("News channels do not support Overwrite Permissions.");
+        /// <inheritdoc />
+        /// <remarks>
+        ///     <note type="important">
+        ///     This method is not supported by this type. Attempting to use this method will result in a <see cref="NotSupportedException"/>.
+        ///     </note>
+        /// </remarks>
         public override Task RemovePermissionOverwriteAsync(IRole role, RequestOptions options = null)
-        {
-            throw new NotSupportedException("News channels do not support Overwrite Permissions.");
-        }
+            => throw new NotSupportedException("News channels do not support Overwrite Permissions.");
+        /// <inheritdoc />
+        /// <remarks>
+        ///     <note type="important">
+        ///     This method is not supported by this type. Attempting to use this method will result in a <see cref="NotSupportedException"/>.
+        ///     </note>
+        /// </remarks>
         public override Task RemovePermissionOverwriteAsync(IUser user, RequestOptions options = null)
-        {
-            throw new NotSupportedException("News channels do not support Overwrite Permissions.");
-        }
+            => throw new NotSupportedException("News channels do not support Overwrite Permissions.");
     }
 }