From 69ed55d4ce0b349bd271a1e7364b1b6afb4923d8 Mon Sep 17 00:00:00 2001 From: CyberCyclist Date: Tue, 10 Apr 2018 21:31:24 -0700 Subject: [PATCH 1/7] Improve clarity of installing guide Minor changes in several sentences. --- docs/guides/getting_started/installing.md | 29 +++++++++++------------ 1 file changed, 14 insertions(+), 15 deletions(-) diff --git a/docs/guides/getting_started/installing.md b/docs/guides/getting_started/installing.md index 5d4c85d81..47012e85f 100644 --- a/docs/guides/getting_started/installing.md +++ b/docs/guides/getting_started/installing.md @@ -2,8 +2,8 @@ title: Installing Discord.Net --- -Discord.Net is distributed through the NuGet package manager, and it -is recommended to use NuGet to get started. +Discord.Net is distributed through the NuGet package manager, and we +recommend installing Discord.Net with NuGet. Optionally, you may compile from source and install yourself. @@ -13,10 +13,9 @@ Currently, Discord.Net targets [.NET Standard] 1.3 and offers support for .NET Standard 1.1. If your application will be targeting .NET Standard 1.1, please see the [additional steps]. -Since Discord.Net is built on the .NET Standard, it is also -recommended to create applications using [.NET Core], though not -required. When using .NET Framework, it is suggested to target -`.NET Framework 4.6.1` or higher. +Since Discord.Net is built on the .NET Standard, we recommend you +creating applications using [.NET Core]. When using .NET Framework, +you should target `.NET Framework 4.6.1` or higher. [.NET Standard]: https://docs.microsoft.com/en-us/dotnet/articles/standard/library [.NET Core]: https://docs.microsoft.com/en-us/dotnet/articles/core/ @@ -86,7 +85,7 @@ you're installing from the developer feed. # Compiling from Source -In order to compile Discord.Net, you require the following: +In order to compile Discord.Net, acquire the following: ### Using Visual Studio @@ -104,14 +103,14 @@ Studio installation. ## Installing on .NET Standard 1.1 -For applications targeting a runtime corresponding with .NET Standard -1.1 or 1.2, the builtin WebSocket and UDP provider will not work. For -applications which utilize a WebSocket connection to Discord -(WebSocket or RPC), third-party provider packages will need to be -installed and configured. +For applications targeting a runtime environment corresponding with +.NET Standard 1.1 or 1.2, the built-in WebSocket and UDP provider will +not work. For applications utilizing a WebSocket connection to Discord +(WebSocket or RPC), third-party provider packages will need to be installed +and configured. -First, install the following packages through NuGet, or compile -yourself, if you prefer: +First, install the following packages through NuGet, or compile the +following packages yourself: - Discord.Net.Providers.WS4Net - Discord.Net.Providers.UDPClient @@ -120,7 +119,7 @@ Note that `Discord.Net.Providers.UDPClient` is _only_ required if your bot will be utilizing voice chat. Next, you will need to configure your [DiscordSocketClient] to use -these custom providers over the default ones. +these third-party providers over the default ones. To do this, set the `WebSocketProvider` and the optional `UdpSocketProvider` properties on the [DiscordSocketConfig] that you From 7f546fa386be2958186c09e8327ed259050d4aa3 Mon Sep 17 00:00:00 2001 From: CyberCyclist Date: Tue, 10 Apr 2018 21:44:36 -0700 Subject: [PATCH 2/7] Improve clarity of installing guide Change instructions of Installing on .NET Standard 1.1 to an ordered list and several rewording. --- docs/guides/getting_started/installing.md | 24 +++++++++++------------ 1 file changed, 11 insertions(+), 13 deletions(-) diff --git a/docs/guides/getting_started/installing.md b/docs/guides/getting_started/installing.md index 47012e85f..2e44f9ca8 100644 --- a/docs/guides/getting_started/installing.md +++ b/docs/guides/getting_started/installing.md @@ -5,7 +5,7 @@ title: Installing Discord.Net Discord.Net is distributed through the NuGet package manager, and we recommend installing Discord.Net with NuGet. -Optionally, you may compile from source and install yourself. +Alternatively, you may compile from source and install yourself. # Supported Platforms @@ -105,25 +105,23 @@ Studio installation. For applications targeting a runtime environment corresponding with .NET Standard 1.1 or 1.2, the built-in WebSocket and UDP provider will -not work. For applications utilizing a WebSocket connection to Discord -(WebSocket or RPC), third-party provider packages will need to be installed -and configured. +not work. Install and configure third-party provider packages for applications +utilizing a WebSocket or an RPC connection to Discord. -First, install the following packages through NuGet, or compile the -following packages yourself: +1. Install the following packages through NuGet, or compile the following +packages yourself: - Discord.Net.Providers.WS4Net - Discord.Net.Providers.UDPClient -Note that `Discord.Net.Providers.UDPClient` is _only_ required if your -bot will be utilizing voice chat. +`Discord.Net.Providers.UDPClient` is _only_ required if your bot will be +utilizing voice chat. -Next, you will need to configure your [DiscordSocketClient] to use -these third-party providers over the default ones. +2. Configure your [DiscordSocketClient] to use these third-party providers +over the default ones. -To do this, set the `WebSocketProvider` and the optional -`UdpSocketProvider` properties on the [DiscordSocketConfig] that you -are passing into your client. +Set the `WebSocketProvider` and optionally the `UdpSocketProvider` properties +in the [DiscordSocketConfig] and pass the config into your client. [!code-csharp[NET Standard 1.1 Example](samples/netstd11.cs)] From e13b22d4cc10cde8e7bfef26ef827cf2b0a76442 Mon Sep 17 00:00:00 2001 From: CyberCyclist Date: Tue, 10 Apr 2018 22:34:35 -0700 Subject: [PATCH 3/7] Improve clarity of installing guide Use embedded note syntax. --- docs/guides/getting_started/installing.md | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/guides/getting_started/installing.md b/docs/guides/getting_started/installing.md index 2e44f9ca8..7f1430aa0 100644 --- a/docs/guides/getting_started/installing.md +++ b/docs/guides/getting_started/installing.md @@ -114,6 +114,7 @@ packages yourself: - Discord.Net.Providers.WS4Net - Discord.Net.Providers.UDPClient +>[!NOTE] `Discord.Net.Providers.UDPClient` is _only_ required if your bot will be utilizing voice chat. From 03be627c4b1465c5b7aca1566dad44478269c2e7 Mon Sep 17 00:00:00 2001 From: CyberCyclist Date: Tue, 10 Apr 2018 23:28:03 -0700 Subject: [PATCH 4/7] Improve clarity of intro guide --- docs/guides/getting_started/intro.md | 35 ++++++++++++++-------------- 1 file changed, 17 insertions(+), 18 deletions(-) diff --git a/docs/guides/getting_started/intro.md b/docs/guides/getting_started/intro.md index db086df21..1a7565a57 100644 --- a/docs/guides/getting_started/intro.md +++ b/docs/guides/getting_started/intro.md @@ -10,8 +10,7 @@ diverse commands later, but for now, it is a good starting point. ## Creating a Discord Bot -Before you can begin writing your bot, it is necessary to create a bot -account on Discord. +Before writing your bot, create a bot account on Discord. 1. Visit the [Discord Applications Portal]. 2. Create a New Application. @@ -34,10 +33,11 @@ other options!** ## Adding your bot to a server Bots **cannot** use invite links, they must be explicitly invited -through the OAuth2 flow. +through the OAuth2 flow, the industry-standard protocol for +authorization. 1. Open your bot's application on the [Discord Applications Portal]. -2. Retrieve the app's **Client ID**. +2. Retrieve the application's **Client ID**. ![Step 2](images/intro-client-id.png) @@ -49,7 +49,7 @@ through the OAuth2 flow. >[!NOTE] Only servers where you have the `MANAGE_SERVER` permission will be - present in this list. + present in the dropdown menu. ![Step 6](images/intro-add-bot.png) @@ -64,20 +64,18 @@ do that now. (see the [Installing](installing.md) section) Discord.Net uses .NET's [Task-based Asynchronous Pattern (TAP)] extensively - nearly every operation is asynchronous. -It is highly recommended that these operations are awaited in a -properly established async context whenever possible. Establishing an -async context can be problematic, but not hard. +We suggest that asynchronous operations should await in an established +async context whenever possible. -To do so, we will be creating an async main in your console -application, and rewriting the static main method to invoke the new -async main. +To establish an async context, create an async main method in your +console application, and rewrite the static main method to invoke the +new 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 -to Discord later on without needing to worry about setting up the -correct async implementation. +Your program will immediately jump into an async context when starts. +This will allow us to create a connection to Discord later on without +worrying about setting up the correct async implementation. >[!TIP] If your application throws any exceptions within an async context, @@ -93,7 +91,7 @@ async main **will** cause the application to crash. ### Creating a logging method Before we create and configure a Discord client, we will add a method -to handle Discord.Net's log events. +to handle Discord.Net's log events. Check the concept of [logging data]. To allow agnostic support of as many log providers as possible, we log information through a `Log` event with a proprietary `LogMessage` @@ -105,6 +103,7 @@ the Console. [!code-csharp[Async Context](samples/intro/logging.cs)] +[logging data]:../concepts/logging.md [API Documentation]: xref:Discord.Rest.BaseDiscordClient#Discord_Rest_BaseDiscordClient_Log ### Creating a Discord Client @@ -139,7 +138,7 @@ 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 -**this method returns as soon as connection logic has been started!** +**`StartAsync` method returns as soon as connection logic has been started!** Any methods that rely on the client's state should go in an event handler. @@ -234,4 +233,4 @@ should be to separate the program (initialization and command handler), the modules (handle commands), and the services (persistent storage, pure functions, data manipulation). -**todo:** diagram of bot structure \ No newline at end of file +**todo:** diagram of bot structure From 88081ba00f1683c185e8c111e61df431a79c8c91 Mon Sep 17 00:00:00 2001 From: CyberCyclist Date: Tue, 10 Apr 2018 23:32:27 -0700 Subject: [PATCH 5/7] Enforce 70 characters per line on installing guide --- docs/guides/getting_started/installing.md | 21 +++++++++++---------- 1 file changed, 11 insertions(+), 10 deletions(-) diff --git a/docs/guides/getting_started/installing.md b/docs/guides/getting_started/installing.md index 7f1430aa0..462b89b4b 100644 --- a/docs/guides/getting_started/installing.md +++ b/docs/guides/getting_started/installing.md @@ -105,24 +105,25 @@ Studio installation. For applications targeting a runtime environment corresponding with .NET Standard 1.1 or 1.2, the built-in WebSocket and UDP provider will -not work. Install and configure third-party provider packages for applications -utilizing a WebSocket or an RPC connection to Discord. +not work. Install and configure third-party provider packages for +applications utilizing a WebSocket or an RPC connection to Discord. -1. Install the following packages through NuGet, or compile the following -packages yourself: +1. Install the following packages through NuGet, or compile the +following packages yourself: - Discord.Net.Providers.WS4Net - Discord.Net.Providers.UDPClient >[!NOTE] -`Discord.Net.Providers.UDPClient` is _only_ required if your bot will be -utilizing voice chat. +`Discord.Net.Providers.UDPClient` is _only_ required if your bot will +be utilizing voice chat. -2. Configure your [DiscordSocketClient] to use these third-party providers -over the default ones. +2. Configure your [DiscordSocketClient] to use these third-party +providers over the default ones. -Set the `WebSocketProvider` and optionally the `UdpSocketProvider` properties -in the [DiscordSocketConfig] and pass the config into your client. +Set the `WebSocketProvider` and optionally the `UdpSocketProvider` +properties in the [DiscordSocketConfig] and pass the config into +your client. [!code-csharp[NET Standard 1.1 Example](samples/netstd11.cs)] From 823ba5cb7b61e0ad9011b390f21204828916dc0e Mon Sep 17 00:00:00 2001 From: CyberCyclist Date: Tue, 10 Apr 2018 23:50:52 -0700 Subject: [PATCH 6/7] Improve clarity of intro guides --- docs/guides/getting_started/intro.md | 15 ++++++++------- 1 file changed, 8 insertions(+), 7 deletions(-) diff --git a/docs/guides/getting_started/intro.md b/docs/guides/getting_started/intro.md index 1a7565a57..31d9f5bc7 100644 --- a/docs/guides/getting_started/intro.md +++ b/docs/guides/getting_started/intro.md @@ -110,15 +110,16 @@ the Console. Finally, we can create a connection to Discord. Since we are writing a bot, we will be using a [DiscordSocketClient] along with socket -entities. See the [terminology](terminology.md) if you're unsure of -the differences. +entities. See the [terminology](terminology.md) if you're unsure +the differences among `Discord.Net.Rest`, `Discord.Net.Rpc`, +and `Discord.Net.WebSocket`. To do so, create an instance of [DiscordSocketClient] in your async main, passing in a configuration object only if necessary. For most users, the default will work fine. Before connecting, we should hook the client's `Log` event to the -log handler that was just created. Events in Discord.Net work +log handler that you just created. Events in Discord.Net work similarly to other events in C#, so hook this event the way that you typically would. @@ -143,10 +144,10 @@ start connection/reconnection logic. It is important to note that Any methods that rely on the client's state should go in an event handler. -Finally, we will want to block the async main method from returning -until after the application is exited. To do this, we can await an -infinite delay or any other blocking method, such as reading from -the console. +Finally, we will want to block the async main method from returning +when running the application. To block from returning, we can await +an infinite delay or any other blocking method, such as reading +from the console. The following lines can now be added: From 2990bb8261fe88d324aa057da9f4d22de5ff3df1 Mon Sep 17 00:00:00 2001 From: CyberCyclist Date: Wed, 11 Apr 2018 03:19:01 -0700 Subject: [PATCH 7/7] Improve the clarity of intro in guides --- docs/guides/getting_started/intro.md | 17 ++++++++--------- 1 file changed, 8 insertions(+), 9 deletions(-) diff --git a/docs/guides/getting_started/intro.md b/docs/guides/getting_started/intro.md index 31d9f5bc7..47285c8d7 100644 --- a/docs/guides/getting_started/intro.md +++ b/docs/guides/getting_started/intro.md @@ -4,9 +4,9 @@ title: Getting Started # Making a Ping-Pong bot -One of the first steps to getting started with the Discord API is to -write a basic ping-pong bot. We will expand on this to create more -diverse commands later, but for now, it is a good starting point. +This topic introduces the Discord API by instructing you to +write a ping-pong bot who can respond message 'ping' with +'pong'. We would create more diverse commands for the bot later. ## Creating a Discord Bot @@ -120,8 +120,7 @@ users, the default will work fine. Before connecting, we should hook the client's `Log` event to the log handler that you just created. Events in Discord.Net work -similarly to other events in C#, so hook this event the way that -you typically would. +similarly to other events in C#. [An Overview of Events in C#] Next, you will need to "login to Discord" with the `LoginAsync` method. @@ -162,6 +161,7 @@ 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. +[An Overview of Events in C#]:https://docs.microsoft.com/en-us/dotnet/csharp/events-overview [DiscordSocketClient]: xref:Discord.WebSocket.DiscordSocketClient [installation guide]: installing.md#installing-on-net-standard-11 @@ -207,7 +207,7 @@ You should have now added the following lines: Now your first bot is complete. You may continue to add on to this if you desire, but for any bots that will be carrying out multiple -commands, it is strongly recommended to use the command framework as +commands, we strongly recommend you using the command framework as shown below. For your reference, you may view the [completed program]. @@ -229,9 +229,8 @@ For reference, view an [annotated example] of this structure. [annotated example]: samples/intro/structure.cs -It is important to know that the recommended design pattern of bots -should be to separate the program (initialization and command handler), +Separating the program (initialization and command handler), the modules (handle commands), and the services (persistent storage, -pure functions, data manipulation). +pure functions, data manipulation) is a nice design pattern for bot. **todo:** diagram of bot structure