Clean up pages

docs/guides/concepts/entities.md

@@ -2,9 +2,11 @@
 title: Entities
 ---
 
->[!NOTE]
-This article is written with the Socket variants of entities in mind,
-not the general interfaces or Rest/Rpc entities.
+# Entities in Discord.NET
+
+> [!NOTE]
+> This article is written with the Socket variants of entities in mind,
+> not the general interfaces or Rest/Rpc entities.
 
 Discord.Net provides a versatile entity system for navigating the
 Discord API.
@@ -15,9 +17,9 @@ Due to the nature of the Discord API, some entities are designed with
 multiple variants; for example, `SocketUser` and `SocketGuildUser`.
 
 All models will contain the most detailed version of an entity
-possible, even if the type is less detailed. 
+possible, even if the type is less detailed.
 
-For example, in the case of the `MessageReceived` event, a 
+For example, in the case of the `MessageReceived` event, a
 `SocketMessage` is passed in with a channel property of type
 `SocketMessageChannel`. All messages come from channels capable of
 messaging, so this is the only variant of a channel that can cover
@@ -42,11 +44,11 @@ The most basic forms of entities, `SocketGuild`, `SocketUser`, and
 cache, and can be retrieved using the respective `GetXXX` method on
 DiscordSocketClient.
 
->[!TIP]
-It is **vital** that you use the proper IDs for an entity when using
-a GetXXX method. It is recommended that you enable Discord's
-_developer mode_ to allow easy access to entity IDs, found in
-Settings > Appearance > Advanced
+> [!TIP]
+> It is **vital** that you use the proper IDs for an entity when using
+> a GetXXX method. It is recommended that you enable Discord's
+> _developer mode_ to allow easy access to entity IDs, found in
+> Settings > Appearance > Advanced.
 
 More detailed versions of entities can be pulled from the basic
 entities, e.g. `SocketGuild.GetUser`, which returns a 
@@ -54,18 +56,6 @@ entities, e.g. `SocketGuild.GetUser`, which returns a
 `SocketGuildChannel`. Again, you may need to cast these objects to get
 a variant of the type that you need.
 
-### Samples
-
-[!code-csharp[Entity Sample](samples/entities.cs)]
-
-### Tips
-
-Avoid using boxing-casts to coerce entities into a variant, use the
-[`as`] keyword, and a null-conditional operator instead.
-
-This allows you to write safer code and avoid [InvalidCastExceptions].
-
-For example, `(message.Author as SocketGuildUser)?.Nickname`.
+### Sample
 
-[`as`]: https://docs.microsoft.com/en-us/dotnet/csharp/language-reference/keywords/as
-[InvalidCastExceptions]: https://msdn.microsoft.com/en-us/library/system.invalidcastexception(v=vs.110).aspx
+[!code-csharp[Entity Sample](samples/entities.cs)]

docs/guides/concepts/events.md

@@ -2,6 +2,8 @@
 title: Working with Events
 ---
 
+# Events in Discord.NET
+
 Events in Discord.Net are consumed in a similar manner to the standard
 convention, with the exception that every event must be of the type
 `System.Threading.Tasks.Task` and instead of using `EventArgs`, the
@@ -61,7 +63,7 @@ This pattern is typically only found on `EntityUpdated` events.
 #### Cacheable
 
 An event handler with a signature of `Func<Cacheable, Entity, Task>`
-means that the `before`	state of the entity was not provided by the
+means that the `before` state of the entity was not provided by the
 API, so it can either be pulled from the client's cache or
 downloaded from the API.
 
@@ -70,15 +72,12 @@ object.
 
 [Cacheable]: xref:Discord.Cacheable`2
 
-### Samples
-
-[!code-csharp[Event Sample](samples/events.cs)]
+> [!NOTE]
+> Many events relating to a Message entity (i.e. `MessageUpdated` and
+> `ReactionAdded`) rely on the client's message cache, which is
+> **not** enabled by default. Set the `MessageCacheSize` flag in
+> @Discord.WebSocket.DiscordSocketConfig to enable it.
 
-### Tips
+### Sample
 
-Many events relating to a Message entity (i.e. `MessageUpdated` and 
-`ReactionAdded`) rely on the client's message cache, which is
-**not** enabled by default. Set the `MessageCacheSize` flag in
-[DiscordSocketConfig] to enable it.
-
-[DiscordSocketConfig]: xref:Discord.WebSocket.DiscordSocketConfig
+[!code-csharp[Event Sample](samples/events.cs)]

docs/guides/concepts/logging.md

@@ -2,18 +2,26 @@
 title: Logging
 ---
 
-Discord.Net's clients provide a [Log] event that all messages will be
+# Logging in Discord.NET
+
+Discord.Net's clients provide a log event that all messages will be
 dispatched over.
 
 For more information about events in Discord.Net, see the [Events]
 section.
 
-[Log]: xref:Discord.Rest.BaseDiscordClient.Log
 [Events]: events.md
 
-### Usage
+> [!WARNING]
+> Due to the nature of Discord.Net's event system, all log event
+> handlers will be executed synchronously on the gateway thread. If your
+> log output will be dumped to a Web API (e.g. Sentry), you are advised
+> to wrap your output in a `Task.Run` so the gateway thread does not
+> become blocked while waiting for logging data to be written.
+
+### Usage in Client(s)
 
-To receive log events, simply hook the discord client's log method
+To receive log events, simply hook the Discord client's @Discord.Rest.BaseDiscordClient.Log
 to a `Task` with a single parameter of type [LogMessage].
 
 It is recommended that you use an established function instead of a
@@ -24,8 +32,8 @@ to a logging function to write their own messages.
 
 ### Usage in Commands
 
-Discord.Net's [CommandService] also provides a log event, identical
-in signature to other log events.
+Discord.Net's [CommandService] also provides a @Discord.Commands.CommandService.Log 
+event, identical in signature to other log events.
 
 Data logged through this event is typically coupled with a
 [CommandException], where information about the command's context
@@ -34,14 +42,6 @@ and error can be found and handled.
 [CommandService]: xref:Discord.Commands.CommandService
 [CommandException]: xref:Discord.Commands.CommandException
 
-#### Samples
+### Sample
 
 [!code-csharp[Logging Sample](samples/logging.cs)]
-
-#### Tips
-
-Due to the nature of Discord.Net's event system, all log event
-handlers will be executed synchronously on the gateway thread. If your
-log output will be dumped to a Web API (e.g. Sentry), you are advised
-to wrap your output in a `Task.Run` so the gateway thread does not
-become blocked while waiting for logging data to be written.

docs/guides/getting_started/installing.md

@@ -27,12 +27,12 @@ required. When using .NET Framework, it is suggested to target
 Release builds of Discord.Net will be published to the
 [official NuGet feed].
 
-Development builds of Discord.Net, as well as addons *(TODO)* are
-published to our development [MyGet feed].
+Development builds of Discord.Net, as well as add-ons are published to
+our development [MyGet feed].
 
 Direct feed link: `https://www.myget.org/F/discord-net/api/v3/index.json`
 
-Not sure how to add a direct feed? See how [with Visual Studio] or 
+Not sure how to add a direct feed? See how [with Visual Studio] or
 [without Visual Studio].
 
 [official NuGet feed]: https://nuget.org

docs/guides/getting_started/intro.md

@@ -15,16 +15,15 @@ account on Discord.
 
 1. Visit the [Discord Applications Portal].
 2. Create a New Application.
-3. Give the application a name (this will be the bot's initial
-username).
+3. Give the application a name (this will be the bot's initial username).
 4. Create the Application.
-	
-	![Step 4](images/intro-create-app.png)
-	
+
+    ![Step 4](images/intro-create-app.png)
+
 5. In the application review page, click **Create a Bot User**.
-	
-	![Step 5](images/intro-create-bot.png)
-	
+
+    ![Step 5](images/intro-create-bot.png)
+
 6. Confirm the popup.
 7. If this bot will be public, check "Public Bot." **Do not tick any 
 other options!**
@@ -33,26 +32,25 @@ other options!**
 
 ## Adding your bot to a server
 
-Bots **cannot** use invite links, they must be explicitly invited
+Bots **cannot** use invite links; they must be explicitly invited
 through the OAuth2 flow.
 
 1. Open your bot's application on the [Discord Applications Portal].
 2. Retrieve the app's **Client ID**.
-	
-	![Step 2](images/intro-client-id.png)
-	
+
+    ![Step 2](images/intro-client-id.png)
+
 3. Create an OAuth2 authorization URL
 `https://discordapp.com/oauth2/authorize?client_id=<CLIENT ID>&scope=bot`
 4. Open the authorization URL in your browser.
 5. Select a server.
 6. Click on authorize.
-	
-	>[!NOTE]
-	Only servers where you have the `MANAGE_SERVER` permission will be
-	present in this list.
-	
-	![Step 6](images/intro-add-bot.png)
 
+    > [!NOTE]
+    > Only servers where you have the `MANAGE_SERVER` permission will be
+    > present in this list.
+
+    ![Step 6](images/intro-add-bot.png)
 
 ## Connecting to Discord
 
@@ -75,7 +73,7 @@ async main.
 [!code-csharp[Async Context](samples/intro/async-context.cs)]
 
 As a result of this, your program will now start and immediately
-jump into an async context. This will allow us to create a connection 
+jump into an async context. This will allow us to create a connection
 to Discord later on without needing to worry about setting up the
 correct async implementation.
 
@@ -123,7 +121,7 @@ log handler that was just created. Events in Discord.Net work
 similarly to other events in C#, so hook this event the way that
 you typically would.
 
-Next, you will need to "login to Discord" with the `LoginAsync` 
+Next, you will need to "login to Discord" with the `LoginAsync`
 method.
 
 You may create a variable to hold your bot's token (this can be found
@@ -131,11 +129,11 @@ on your bot's application page on the [Discord Applications Portal]).
 
 ![Token](images/intro-token.png)
 
->[!IMPORTANT]
-Your bot's token can be used to gain total access to your bot, so
-**do __NOT__ share this token with anyone else!** It may behoove you 
-to store this token in an external file if you plan on distributing 
-the source code for your bot.
+> [!IMPORTANT]
+> Your bot's token can be used to gain total access to your bot, so
+> **do __NOT__ share this token with anyone else!** It may behoove you
+> to store this token in an external file if you plan on distributing
+> the source code for your bot.
 
 We may now invoke the client's `StartAsync` method, which will
 start connection/reconnection logic. It is important to note that
@@ -156,27 +154,26 @@ The following lines can now be added:
 At this point, feel free to start your program and see your bot come
 online in Discord.
 
->[!TIP]
-Encountering a `PlatformNotSupportedException` when starting your bot?
-This means that you are targeting a platform where .NET's default
-WebSocket client is not supported. Refer to the [installation guide]
-for how to fix this.
+> [!TIP]
+> Encountering a `PlatformNotSupportedException` when starting your bot?
+> This means that you are targeting a platform where .NET's default
+> WebSocket client is not supported. Refer to the [installation guide]
+> for how to fix this.
 
 [DiscordSocketClient]: xref:Discord.WebSocket.DiscordSocketClient
 [installation guide]: installing.md#installing-on-net-standard-11
 
 ### Handling a 'ping'
 
->[!WARNING]
-Please note that this is *not* a proper way to create a command.
-Use the `CommandService` provided by the library instead, as explained
-in the [Command Guide] section.
+> [!WARNING]
+> Please note that this is *not* a proper way to create a command.
+> Use the `CommandService` provided by the library instead, as explained
+> in the [Command Guide] section.
 
 Now that we have learned how to open a connection to Discord, we can
-begin handling messages that users are sending.
-
-To start out, our bot will listen for any message where the content
-is equal to `!ping` and respond back with "Pong!".
+begin handling messages that users are sending. To start out, our bot
+will listen for any message where the content is equal to `!ping` and
+respond back with "Pong!".
 
 Since we want to listen for new messages, the event to hook into
 is [MessageReceived].
@@ -201,7 +198,7 @@ channel object is of type [SocketMessageChannel], we can invoke the
 `SendMessageAsync` instance method. For the message content, send back
 a string containing "Pong!".
 
-You should have now added the following lines:
+You should have now added the following lines,
 
 [!code-csharp[Message](samples/intro/message.cs)]
 

docs/guides/getting_started/samples/project.csproj

@@ -1,17 +1,15 @@
 <Project Sdk="Microsoft.NET.Sdk">
-
   <!--
   The following may differ depending on the latest version of 
   .NET Core Framework or Discord.NET.
   -->
   <PropertyGroup>
     <OutputType>Exe</OutputType>
-    <TargetFramework>netcoreapp1.1</TargetFramework>
-    <NoWin32Manifest>true</NoWin32Manifest>
+    <TargetFramework>netcoreapp2.0</TargetFramework>
   </PropertyGroup>
 
   <ItemGroup>
-    <PackageReference Include="Discord.Net" Version="1.*" />
+    <PackageReference Include="Discord.Net" Version="2.*" />
   </ItemGroup>
 
 </Project>