diff --git a/docs/guides/getting_started/installing.md b/docs/guides/getting_started/installing.md index 5d4c85d81..462b89b4b 100644 --- a/docs/guides/getting_started/installing.md +++ b/docs/guides/getting_started/installing.md @@ -2,10 +2,10 @@ 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. +Alternatively, you may compile from source and install yourself. # Supported Platforms @@ -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,27 +103,27 @@ 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. 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 -yourself, if you prefer: +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. +>[!NOTE] +`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. +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)] diff --git a/docs/guides/getting_started/intro.md b/docs/guides/getting_started/intro.md index db086df21..47285c8d7 100644 --- a/docs/guides/getting_started/intro.md +++ b/docs/guides/getting_started/intro.md @@ -4,14 +4,13 @@ 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 -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,23 +103,24 @@ 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 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 -similarly to other events in C#, so hook this event the way that -you typically would. +log handler that you just created. Events in Discord.Net work +similarly to other events in C#. [An Overview of Events in C#] Next, you will need to "login to Discord" with the `LoginAsync` method. @@ -139,15 +138,15 @@ 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. -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: @@ -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 \ No newline at end of file +**todo:** diagram of bot structure