clean up docs, remake (DSharpPlus#1517)

* clean up docs, remake * reformat docfx.json * reformat markdown fix typo in vnext article
Indexium · Mar 22, 2023 · 6012083 · 6012083
1 parent b18e6e0
commit 6012083
Show file tree

Hide file tree

Showing 70 changed files with 668 additions and 2,309 deletions.
diff --git a/BUILDING.md b/BUILDING.md
@@ -1,28  1,32 @@
 # Building DSharpPlus
 
 These are detailed instructions on how to build the DSharpPlus library under various environmnets.
 
 It is recommended you have prior experience with multi-target .NET Core/Standard projects, as well as the `dotnet` CLI utility, and MSBuild.
 
 ## Requirements
 
 In order to build the library, you will first need to install some software.
 
 ### Windows
 
 On Windows, we only officially support Visual Studio 2017 15.3 or newer. Visual Studio Code and other IDEs might work, but are generally not supported or even guaranteed to work properly.
 
 * **Windows 10** - while we support running the library on Windows 7 and above, we only support building on Windows 10.
 * [**Git for Windows**](https://git-scm.com/download/win) - required to clone the repository.
 * [**Visual Studio 2017**](https://www.visualstudio.com/downloads/) - community edition or better. We do not support Visual Studio 2015 and older. Note that to build the library, you need Visual Studio 2017 version 15.3 or newer.
-   * **Workloads**:
-      * **.NET Framework Desktop** - required to build .NETFX (4.5, 4.6, and 4.7 targets)
-      * **.NET Core Cross-Platform Development** - required to build .NET Standard targets (1.1, 1.3, and 2.0) and the project overall.
-   * **Individual Components**:
-      * **.NET Framework 4.5 SDK** - required for .NETFX 4.5 target
-      * **.NET Framework 4.6 SDK** - required for .NETFX 4.6 target
-      * **.NET Framework 4.7 SDK** - required for .NETFX 4.7 target
   * **Workloads**:
     * **.NET Framework Desktop** - required to build .NETFX (4.5, 4.6, and 4.7 targets)
     * **.NET Core Cross-Platform Development** - required to build .NET Standard targets (1.1, 1.3, and 2.0) and the project overall.
   * **Individual Components**:
     * **.NET Framework 4.5 SDK** - required for .NETFX 4.5 target
     * **.NET Framework 4.6 SDK** - required for .NETFX 4.6 target
     * **.NET Framework 4.7 SDK** - required for .NETFX 4.7 target
 * [**.NET Core SDK 2.0**](https://www.microsoft.com/net/download) - required to build the project.
 * **Windows PowerShell** - required to run the build scripts. You need to make sure your script execution policy allows execution of unsigned scripts.
 
 ### GNU/Linux
 
 On GNU/Linux, we support building via Visual Studio Code and .NET Core SDK. Other IDEs might work, but are not supported or guaranteed to work properly.
 
 While these should apply to any modern distribution, we only test against Debian 10. Your mileage may vary.
@@ -32,19  36,22 @@ When installing the below, make sure you install all the dependencies properly.
 * **Any modern GNU/Linux distribution** - like Debian 9.
 * **Git** - to clone the repository.
 * [**Visual Studio Code**](https://code.visualstudio.com/Download) - a recent version is required.
-   * **C# for Visual Studio Code (powered by OmniSharp)** - required for syntax highlighting and basic Intellisense
   * **C# for Visual Studio Code (powered by OmniSharp)** - required for syntax highlighting and basic Intellisense
 * [**.NET Core SDK 2.0**](https://www.microsoft.com/net/download) - required to build the project.
 * [**Mono 5.x**](http://www.mono-project.com/download/#download-lin) - required to build the .NETFX 4.5, 4.6, and 4.7 targets, as well as to build the docs.
 * [**PowerShell Core**](https://docs.microsoft.com/en-us/powershell/scripting/setup/Installing-PowerShell-Core-on-macOS-and-Linux?view=powershell-6) - required to execute the build scripts.
 * **p7zip-full** - required to package docs.
 
 ## Instructions
 
 Once you install all the necessary prerequisites, you can proceed to building. These instructions assume you have already cloned the repository.
 
 ### Windows
 
 Building on Windows is relatively easy. There's 2 ways to build the project:
 
 #### Building through Visual Studio
 
 Building through Visual Studio yields just binaries you can use in your projects.
 
 1. Open the solution in Visual Studio.
@@ -53,22  60,26 @@ Building through Visual Studio yields just binaries you can use in your projects
 4. Select Build > Publish DSharpPlus to publish the binaries.
 
 #### Building with the build script
 
 Building this way outputs NuGet packages, and a documentation package. Ensure you have an internet connection available, as the script will install programs necessary to build the documentation.
 
 1. Open PowerShell and navigate to the directory which you cloned DSharpPlus to.
 2. Execute `.\rebuild-all.ps1 -configuration Release` and wait for the script to finish execution.
 3. Once it's done, the artifacts will be available in *dsp-artifacts* directory, next to the directory to which the repository is cloned.
 
 ### GNU/Linux
 
 When all necessary prerequisites are installed, you can proceed to building. There are technically 2 ways to build the library, though both of them perform the same steps, they are just invoked slightly differently.
 
 #### Through Visual Studio Code
 
 1. Open Visual Studio Code and open the folder to which you cloned DSharpPlus as your workspace.
 2. Select Build > Run Task...
 3. Select `buildRelease` task and wait for it to finish.
 4. The artifacts will be placed in *dsp-artifacts* directory, next to whoch the repository is cloned.
 
 #### Through PowerShell
 
 1. Open PowerShell (`pwsh`) and navigate to the directory which you cloned DSharpPlus to.
 2. Execute `.\rebuild-all.ps1 -configuration Release` and wait for the script to finish execution.
 3. Once it's done, the artifacts will be available in *dsp-artifacts* directory, next to the directory to which the repository is cloned.
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -1,18  1,23 @@
 # Contributing to DSharpPlus
 
 We're really happy to accept contributions. However we also ask that you follow several rules when doing so.
 
 # Proper base
 
 When opening a PR, please make sure your branch targets the latest master branch. Also make sure your branch is even with the target branch, to avoid unnecessary surprises.
 
 # Versioning
-We follow [SemVer](https://semver.org/) versioning when it comes to pushing stable releases. Ideally, this means you should only be creating PRs for `patch` and `minor` changes. If you wish to introduce a `major` (breaking) change, please discuss it beforehand so we can determine how to integrate it into our next major version. If this involves removing a public facing property/method, mark it with the `Obsolete` attribute instead on the latest release branch. 
 
 We follow [SemVer](https://semver.org/) versioning when it comes to pushing stable releases. Ideally, this means you should only be creating PRs for `patch` and `minor` changes. If you wish to introduce a `major` (breaking) change, please discuss it beforehand so we can determine how to integrate it into our next major version. If this involves removing a public facing property/method, mark it with the `Obsolete` attribute instead on the latest release branch.
 
 # Proper titles
-When opening issues, make sure the title reflects the purpose of the issue or the pull request. Prefer past tense, and 
 
 When opening issues, make sure the title reflects the purpose of the issue or the pull request. Prefer past tense, and
 be brief. Further description belongs inside the issue or PR.
 
 # Descriptive changes
-We require the commits describe the change made. It can be a short description. If you fixed or resolved an open issue, 
 
 We require the commits describe the change made. It can be a short description. If you fixed or resolved an open issue,
 please reference it by using the # notation.
 
 Examples of good commit messages:
@@ -21,6  26,7 @@ Examples of good commit messages:
 * `Implemented new command extension. Resolves #169.`
 * `Changed message cache behaviour. It's now global instead of per-channel.`
 * `Fixed a potential NRE.`
 
 * ```
   Changed message cache behaviour:
   
@@ -37,11  43,12 @@ Examples of bad commit messages:
 * `Oops.`
 
 # Code style
-We use [Microsoft C# Coding Conventions](https://docs.microsoft.com/en-us/dotnet/csharp/programming-guide/inside-a-program/coding-conventions) 
 
 We use [Microsoft C# Coding Conventions](https://docs.microsoft.com/en-us/dotnet/csharp/programming-guide/inside-a-program/coding-conventions)
 throughout the repository, with several exceptions:
 
 * Preference of `this`. While this one is not required, it's ill-advised to remove the existing instances thereof.
-* When working with async code, and your method consists of a single `await` statement not in any `if`, `while`, etc. 
 * When working with async code, and your method consists of a single `await` statement not in any `if`, `while`, etc.
   blocks, pass the task through instead of awaiting it. For example:
 
   ```cs
@@ -82,42  89,45 @@ In addition to these, we also have several preferences:
 
   var d = new[] { 42, 69 };
   ```
 
 * Inline `out` declarations when possible: `SomeOutMethod(42, out var stringified);`
 * Members in classes should be ordered as follows (with few exceptions):
-   * Public `const` fields.
-   * Non-public `const` fields.
-   * Public static properties.
-   * Public static fields.
-   * Non-public static properties.
-   * Non-public static fields.
-   * Public properties.
-   * Public fields.
-   * Private properties.
-   * Private fields.
-   * Static constructor.
-   * Public constructors.
-   * Non-public constructors.
-   * Public methods (with the exception of methods overriden from `System.Object`).
-   * Non-public methods.
-   * Methods overriden from `System.Object`.
-   * Public static methods.
-   * Non-public static methods.
-   * Operator overloads.
-   * Public events.
-   * Non-public events.
   * Public `const` fields.
   * Non-public `const` fields.
   * Public static properties.
   * Public static fields.
   * Non-public static properties.
   * Non-public static fields.
   * Public properties.
   * Public fields.
   * Private properties.
   * Private fields.
   * Static constructor.
   * Public constructors.
   * Non-public constructors.
   * Public methods (with the exception of methods overriden from `System.Object`).
   * Non-public methods.
   * Methods overriden from `System.Object`.
   * Public static methods.
   * Non-public static methods.
   * Operator overloads.
   * Public events.
   * Non-public events.
 
 # Code changes
-One of our requirements is that all code change commits must build successfully. This is verified by our CI. When you 
-open a pull request, Github will start an action which will perform a build and create PR artifacts. You can view its summary by visiting it from the checks section on 
 
 One of our requirements is that all code change commits must build successfully. This is verified by our CI. When you
 open a pull request, Github will start an action which will perform a build and create PR artifacts. You can view its summary by visiting it from the checks section on
 the PR overview page.
 
 PRs that do not build will not be accepted.
 
 Furthermore we require that methods you implement on Discord entities have a reflection in the Discord API.
 
-In the event your code change is a style change, XML doc change, or otherwise does not change how the code works, tag 
 In the event your code change is a style change, XML doc change, or otherwise does not change how the code works, tag
 the commit with `[ci skip]`.
 
 # Non-code changes
-In the event you change something outside of code (i.e. a meta-change or documentation), you must tag your commit with 
 
 In the event you change something outside of code (i.e. a meta-change or documentation), you must tag your commit with
 `[ci skip]`.
diff --git a/README.md b/README.md
@@ -1,6  1,7 @@
 ![Logo of DSharpPlus](https://github.com/DSharpPlus/DSharpPlus/raw/master/logo/dsharp _smaller.png)
 
 # DSharpPlus
 
 An unofficial .NET wrapper for the Discord API, based off [DiscordSharp](https://github.com/suicvne/DiscordSharp), but rewritten to fit the API standards.
 
 [![Nightly Build Status](https://github.com/DSharpPlus/DSharpPlus/actions/workflows/publish_nightly_master.yml/badge.svg?branch=master)](https://github.com/DSharpPlus/DSharpPlus/actions/workflows/publish_nightly_master.yml)
@@ -9,6  10,7 @@ An unofficial .NET wrapper for the Discord API, based off [DiscordSharp](https:/
 [![NuGet Latest Nightly/Prerelease](https://img.shields.io/nuget/vpre/DSharpPlus?color=505050&label=NuGet Latest Nightly/Prerelease)](https://nuget.org/packages/DSharpPlus)
 
 # Installing
 
 You can install the library from following sources:
 
 1. All Nightly versions are available on [Nuget](https://www.nuget.org/packages/DSharpPlus/) as a pre-release. These are cutting-edge versions automatically built from the latest commit in the `master` branch in this repository, and as such always contains the latest changes. If you want to use the latest features on Discord, you should use the nightlies.
@@ -20,38  22,48 @@ You can install the library from following sources:
    Critical bugfixes in the nightly releases will usually be backported to the latest major stable release, but only after they have passed our soak tests. Additionally, some smaller fixes may be infrastructurally impossible or very difficult to backport without "breaking everything", and as such they will remain only in the nightly release until the next major release. You should evaluate whether or not this version suits your specific needs.
 
 3. The library can be directly referenced from your csproj file. Cloning the repository and referencing the library is as easy as:
 
     ```
     git clone https://github.com/DSharpPlus/DSharpPlus.git DSharpPlus-Repo
     ```
 
     Edit MyProject.csproj and add the following line:
 
     ```xml
     <ProjectReference Include="../DSharpPlus-Repo/DSharpPlus/DSharpPlus.csproj" />
     ```
 
     This belongs in the ItemGroup tag with the rest of your dependencies. The library should not be in the same directory or subdirectory as your project. This method should only be used if you're making local changes to the library.
 
 # Documentation
 
 The documentation for the latest stable version is available at [dsharpplus.github.io](https://dsharpplus.github.io/DSharpPlus).
 
 ## Resources
 
 The following resources apply only for the latest stable version of the library.
 
 ### Tutorials
 
 * [Making your first bot in C#](https://dsharpplus.github.io/DSharpPlus/articles/basics/bot_account.html).
 
 ### Example bots
 
 * [Example by OoLunar](https://github.com/DSharpPlus/Example-Bots)
 
-# I want to throw my money at you!
 # I want to throw my money at you
 
 If you want to give us some money as a thank you gesture, you can do so using one of these links:
 
 * Naamloos
-   * [Ko-Fi](https://ko-fi.com/naamloos)
   * [Ko-Fi](https://ko-fi.com/naamloos)
 * Emzi0767
-   * [Ko-Fi](https://ko-fi.com/emzi0767)
-   * [PayPal](https://paypal.me/Emzi0767/5USD)
-   * [Patreon](https://patreon.com/emzi0767)
   * [Ko-Fi](https://ko-fi.com/emzi0767)
   * [PayPal](https://paypal.me/Emzi0767/5USD)
   * [Patreon](https://patreon.com/emzi0767)
 
 # Questions?
 
 Come talk to us here:
 
 [![DSharpPlus Chat](https://discord.com/api/guilds/379378609942560770/embed.png?style=banner1)](https://discord.gg/dsharpplus)