From 6612a03bee4f8e9d65c9ccd9a801ef301a045cdc Mon Sep 17 00:00:00 2001 From: Hsu Still <341464@gmail.com> Date: Fri, 30 Mar 2018 15:59:26 +0800 Subject: [PATCH] Clean up pages --- docs/guides/concepts/entities.md | 38 ++++------ docs/guides/concepts/events.md | 21 +++--- docs/guides/concepts/logging.md | 30 ++++---- docs/guides/getting_started/installing.md | 6 +- docs/guides/getting_started/intro.md | 75 +++++++++---------- .../getting_started/samples/project.csproj | 6 +- 6 files changed, 80 insertions(+), 96 deletions(-) diff --git a/docs/guides/concepts/entities.md b/docs/guides/concepts/entities.md index 3a5d5496b..49139cecf 100644 --- a/docs/guides/concepts/entities.md +++ b/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 \ No newline at end of file +[!code-csharp[Entity Sample](samples/entities.cs)] \ No newline at end of file diff --git a/docs/guides/concepts/events.md b/docs/guides/concepts/events.md index 47db49aa8..758e5e6d8 100644 --- a/docs/guides/concepts/events.md +++ b/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` -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 \ No newline at end of file +[!code-csharp[Event Sample](samples/events.cs)] diff --git a/docs/guides/concepts/logging.md b/docs/guides/concepts/logging.md index ae2acdf0f..52fccd02b 100644 --- a/docs/guides/concepts/logging.md +++ b/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. \ No newline at end of file diff --git a/docs/guides/getting_started/installing.md b/docs/guides/getting_started/installing.md index be5b2494e..e2cee0d5b 100644 --- a/docs/guides/getting_started/installing.md +++ b/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 diff --git a/docs/guides/getting_started/intro.md b/docs/guides/getting_started/intro.md index c0c26e3f1..7afc045ec 100644 --- a/docs/guides/getting_started/intro.md +++ b/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=&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)] diff --git a/docs/guides/getting_started/samples/project.csproj b/docs/guides/getting_started/samples/project.csproj index a964bbc26..79307226d 100644 --- a/docs/guides/getting_started/samples/project.csproj +++ b/docs/guides/getting_started/samples/project.csproj @@ -1,17 +1,15 @@ - Exe - netcoreapp1.1 - true + netcoreapp2.0 - +