Merge remote-tracking branch 'upstream/dev' into constructors

.github/labeler.yml

@@ -25,7 +25,11 @@ packaging:
 - '**Dockerfile'
 submodules:
 - '**.gitmodules'
+- '**doxygen-awesome-css/**' # Ideally, nobody should be touching this, but it's here just in-case.
 github_actions:
-- '**/.github/labeler.yml'
-- '**/.github/dependabot.yml'
-- '**/.github/workflows/**'
+- '**.github/labeler.yml'
+- '**.github/dependabot.yml'
+- '**.github/workflows/**'
+code:
+- '**src/**'
+- '**include/**'

.github/workflows/labeler.yml

@@ -1,6 +1,7 @@
 name: "Pull Request Labeler"
 on:
-- pull_request_target
+  pull_request_target:
+    types: [opened, reopened]
 
 permissions:
   contents: read

.github/workflows/test-docs-examples.yml

@@ -19,7 +19,10 @@ jobs:
   test_docs_examples:
     name: Test build examples
     runs-on: ubuntu-22.04
-
+    concurrency:
+      group: ${{ github.workflow }}-${{ github.ref }}
+      cancel-in-progress: true
+
     steps:
       - name: Harden Runner
         uses: step-security/harden-runner@8ca2b8b2ece13480cda6dacd3511b49857a23c09 # v2.5.1

.vscode/settings.json

@@ -79,6 +79,7 @@
 		"coroutine": "cpp",
 		"numbers": "cpp",
 		"semaphore": "cpp",
-		"stop_token": "cpp"
+		"stop_token": "cpp",
+		"charconv": "cpp"
 	}
 }

docpages/building/freebsd.md

@@ -1,46 +1,74 @@
 \page buildfreebsd Building on FreeBSD
 
+\note This page assumes you are the root user. If you are not, start the package install commands with `sudo`, along with `make install`. You will need `sudo` installed if you are not the root user.
+
 ## 1. Toolchain
-This project uses CMake. Install it with `pkg install cmake`
 
-## 2. Install External Dependencies
-Your FreeBSD base system should have all the required dependencies installed by default.
+Since the project uses `CMake`, you'll need to install it! If you don't have it, you can do the following:
+
+```bash
+pkg install cmake
+```
+
+## 2. Install Voice Dependencies (Optional)
+
+If you wish to use voice support, you'll need to install opus and libsodium:
+
+First, you need to install opus.
+```bash
+cd /usr/ports/audio/opus
+make && make install
+```
 
-For voice support, additional dependencies are required
+Then, you need to install libsodium.
 
-    pkg install libsodium opus pkgconf
+```bash
+cd /usr/ports/security/libsodium
+make && make install
+```
 
 ## 3. Build Source Code
 
-    cmake -B ./build
-    cmake --build ./build -j8
+```bash
+cmake -B ./build
+cmake --build ./build -j8
+```
 
 Replace the number after `-j` with a number suitable for your setup, usually the same as the number of cores on your machine. `cmake` will fetch any dependencies that are required for you and ensure they are compiled alongside the library.
 
-## 4. Install globally
+## 4. Install Globally
 
-    cd build; make install
+```bash
+cd build
+make install
+```
 
-## 5. Installation to a different directory
+## 5. Installation to a Different Directory (Optional)
 
 If you want to install the library, its dependencies and header files to a different directory, specify this directory when running `cmake`:
 
-    cmake .. -DCMAKE_INSTALL_PREFIX=/path/to/install
+```bash
+cmake .. -DCMAKE_INSTALL_PREFIX=/path/to/install
+```
 
-Then once the build is complete, run `make install` to install to the location you specified.
+Then once the build is complete, run `sudo make install` to install to the location you specified.
 
-## 6. Using the library
+## 6. Using the Library
 
 Once installed, you can make use of the library in standalone programs simply by including it and linking to it:
 
-    clang++ -std=c++17 -ldpp mydppbot.cpp -o dppbot
+```bash
+clang++ -std=c++17 -L/usr/local/lib -I/usr/local/include -ldpp bot.cpp -o dppbot
+```
 
 The important flags in this command-line are:
 
- * `-std=c++17` - Required to compile the headers
- * `-ldpp` - Link to libdpp.dylib
- * `mydppbot.cpp` - Your source code
- * `dppbot` - The name of the executable to make
+* `-std=c++17` - Required to compile the headers
+* `-L/usr/local/lib` - Required to tell the linker where libdpp is located.
+* `-I/usr/local/include` - Required to tell the linker where dpp headers are located.
+* `-ldpp` - Link to `libdpp.so`.
+* `bot.cpp` - Your source code.
+* `-o dppbot` - The name of the executable to make.
 
 \include{doc} install_prebuilt_footer.dox
 

docpages/building/openbsd.md

@@ -1,13 +1,17 @@
 \page buildopenbsd Building on OpenBSD
 
+\note This page assumes you are the root user. If you are not, start the package install commands with `doas`, along with `make install`.
+
 ## 1. Toolchain
+
 Since the project uses `CMake`, you'll need to install it! If you don't have it, you can do the following:
 
 ```bash
 pkg_add cmake
 ```
 
 ## 2. Install Voice Dependencies (Optional)
+
 If you wish to use voice support, you'll need to do the following:
 
 ```bash
@@ -23,13 +27,13 @@ cmake --build ./build -j8
 
 Replace the number after `-j` with a number suitable for your setup, usually the same as the number of cores on your machine. `cmake` will fetch any dependencies that are required for you and ensure they are compiled alongside the library.
 
-## 2. Install globally
+## 4. Install Globally
 
 ```bash
-cd build; sudo make install
+cd build; make install
 ```
 
-## 3. Installation to a different directory
+## 5. Installation to a Different Directory
 
 If you want to install the library, its dependencies and header files to a different directory, specify this directory when running `cmake`:
 
@@ -39,21 +43,8 @@ cmake .. -DCMAKE_INSTALL_PREFIX=/path/to/install
 
 Then once the build is complete, run `make install` to install to the location you specified.
 
-## 4. Using the library
-
-Once installed to the `/usr/local` directory, you can make use of the library in standalone programs simply by including it and linking to it:
-
-```bash
-clang++ -std=c++17 mydppbot.cpp -o dppbot -ldpp
-```
-
-The important flags in this command-line are:
-
- * `-std=c++17` - Required to compile the headers
- * `-ldpp` - Link to libdpp.dylib
- * `mydppbot.cpp` - Your source code
- * `dppbot` - The name of the executable to make
+## 6. Using the Library
 
-\include{doc} install_prebuilt_footer.dox
+Once installed to the `/usr/local` directory, you can make use of the library in CMake, without linking to a folder! You can't use this with `clang++`, nor `g++`, as OpenBSD seems to be broken on this end, so your only option from here is to use CMake. This isn't a bad thing, as we recommend people to use CMake anyways!
 
 **Have fun!**

docpages/make_a_bot/meson.md

@@ -1,57 +1,66 @@
-\page buildmeson Build a Discord Bot using Meson
+\page buildmeson Build a Discord Bot Using Meson
 
 ## 1. Toolchain
 
-Before compiling, you will need to install `meson` on your system.
-To be sure that `meson` is installed, you can type the following command:
+Before compiling, you will need to install `meson` on your system. To be sure that `meson` is installed, you can type the following command:
 
-    $ meson --version
-    0.63.2
+```bash
+meson --version
+0.63.2
+```
 
 ## 2. Create a Meson project
 
-In an empty directory.
+First, you'll need to go ahead and create an empty directory, we'll call it `meson-project`.
 
-    - your project/
+Then, run this command:
 
-run the command 
+```bash
+meson init -l cpp
+```
 
-    $ meson init -l cpp
+## 3. Configuring Your Meson Project
 
-## 3. Configuring your Meson project
+Add the following line after the `project()` line in your `meson.build` file.
 
-add the following line after the `project()` line in your `meson.build` file.
-
-    dpp = dependency('dpp')
+```yml
+dpp = dependency('dpp')
+```
 
-add the following line in the executable section of your `meson.build` file.
+Add the following line in the executable section of your `meson.build` file.
 
-    dependencies: [dpp]
+```yml
+dependencies: [dpp]
+```
 
-change the `cpp_std` value in the `project()` to `c++17`
+Change the `cpp_std` value in the `project()` to `c++17`. Your `meson.build` should look like this:
 
 your meson.build should look like this.
-~~~~~~~~~~~~~~
+~~~~~~~~~~~~~~yml
 project('discord-bot', 'cpp',
   version : '0.1',
   default_options : ['warning_level=3',
                      'cpp_std=c++17'])
 
 dpp = dependency('dpp')
 
-
 exe = executable('discord', 'discord_bot.cpp',
   install : true, dependencies: [dpp])
 
 test('basic', exe)
-
 ~~~~~~~~~~~~~~
 
 Meson automatically generates a cpp for your project. And a test suite.
 
 ## 4. Building
 
-To build a meson project run
+To build a Meson project, run the following:
+
+```bash
+meson setup builddir
+meson compile -C builddir
+```
+
+Now, your Meson project should be all setup!
 
-    $ meson setup builddir
-    $ meson compile -C builddir
+**Have fun!**

docpages/make_a_bot/replit.md

@@ -1,42 +1,45 @@
-\page building-a-cpp-discord-bot-in-repl Creating a Discord bot in Replit
+\page building-a-cpp-discord-bot-in-repl Creating a Discord Bot in Replit
 
-@note There is a premade repl, ready for use which was built using the steps above. If you wish to use this repl simply [visit this github repository](https://github.com/alanlichen/dpp-on-repl) and click the "Run on Replit" button. Then, follow the steps in the README file.
+\warning Be aware, Replit changes frequently, meaning DPP may not always work. It is out of our control and you simply have to hope that they change it again. If this is an inconvenience, we recommend you obtain some affordable non-free hosting.
 
-To build a D++ bot in a Replit instance, follow these steps. These steps are slightly more convoluted than installing D++ into a standard container as we don't have access to root in the conventional way or write access to any files outside of our home directory in a repl. This guide sidesteps the issue by locally extracting a libdpp deb file installer, and referencing the local dependencies from the command-line.
+\note There is a premade repl, ready for use, which was built using the steps below. If you wish to use this repl simply [visit this GitHub repository](https://github.com/alanlichen/dpp-on-repl) and click the "Run on Replit" button. Then, follow the steps in the README file. 
 
-1. Use wget, or the upload button, to get the precompiled x64 release into your repl as a file, e.g. `wget -O libdpp.deb https://dl.dpp.dev/latest`
+To build a D++ bot in a Replit instance, follow these steps. These steps are slightly more convoluted than installing D++ into a standard container as we don't have access to root in the conventional way or write access to any files outside of our home directory in a repl. This guide sidesteps the issue by locally extracting a `libdpp` deb file installer, and referencing the local dependencies from the command-line.
+
+1. Use wget, or the upload button, to get the precompiled x64 release into your repl as a file, e.g. `wget -O libdpp.deb https://dl.dpp.dev/latest`,
 2. Extract this deb file using `dpkg`:
-```
+```bash
 dpkg -x libdpp.deb .
 ```
 3. Compile your bot, note that you should be sure to include the `pthread` library explicitly and reference the extracted dpp installation you just put into the repl:
-```
+```bash
 g++ -o bot main.cpp -ldpp -lpthread -L./usr/lib -I./usr/include -std=c++17
 ```
 4. Run your bot! Note that you will need to set `LD_PRELOAD` to reference `libdpp.so` as it will be located in `$HOME` and not `/usr/lib`:
-```
+```bash
 LD_PRELOAD=./usr/lib/libdpp.so ./bot
 ```
 
 Now that your bot is running, you have to keep it online. Replit automatically puts repls to sleep after some time, so you will need to ping a webserver. Unfortunately, Replit is sometimes limiting, and this is one of the only free workarounds to this issue.
 
 1. Start a http server. This can be through any webserver, but as a simple solution, use python's built in http.server:
-```
+```bash
 python3 -m http.server
 ```
 2. Create an `index.html` file with anything inside it for the server to serve.
 3. Go to [uptimerobot.com](https://uptimerobot.com/) and create an account if you don't have one.
 4. After verifying your account, click "Add New Monitor".
 + For Monitor Type, select "HTTP(s)"
 + In Friendly Name, put the name of your bot
-+ For your url, copy the url of the new website that repl is serving for you
++ For your URL, copy the URL of the new website that repl is serving for you
 + Select any alert contacts you want, then click "Create Monitor"
+
 Here is an example of a possible uptimerobot configuration:
 
 \image html uptimerobot.png
 
 ## Troubleshooting
 
-If the bot fails to start and instead you receive an error message about being banned from the Discord API, there is little to be done about this. These bans are temporary but because Replit is a shared platform, you share an IP address with many thousands of bots, some abusive and some badly written. This will happen often and is outside of the control of yourself and us. However, you can try to migitate this by typing `kill 1` in the shell. This is not guaranteed to work, and you might need to try it a few times. If it still does not work, then we recommend instead you obtain some affordable non-free hosting instead.
+- If the bot fails to start and instead you receive an error message about being banned from the Discord API, there is little to be done about this. These bans are temporary but because Replit is a shared platform, you share an IP address with many thousands of bots, some abusive and some badly written. This will happen often and is outside of the control of yourself and us. However, you can try to mitigate this by typing `kill 1` in the shell. This is not guaranteed to work, and you might need to try it a few times. If it still does not work, then we recommend you obtain some affordable non-free hosting instead.
 
-If your bot continues to fall asleep even though you have a server, we advise you to double check that no errors are happening, and if the server is being pinged. If that still does not work, we again recommend you to obtain some affordable non-free hosting.
+- If your bot continues to fall asleep even though you have a server, we advise you to double check that no errors are happening, and if the server is being pinged. If that still does not work then, again, we recommend you obtain some affordable non-free hosting.

docpages/make_a_bot/token.md

@@ -1,8 +1,8 @@
 \page creating-a-bot-application Creating a Bot Token
 
-Before you start coding, you need to create and register your bot in the Discord developer portal. You can then add this bot to your Discord-server.
+Before you start coding, you need to create and register your bot in the Discord developer portal. You can then add this bot to your Discord server.
 
-## Creating a new bot
+## Creating a New Bot
 
 To create a new application, take the steps as follows:
 
@@ -11,35 +11,30 @@ To create a new application, take the steps as follows:
 \image html create_application_confirm_popup.png
 In this example we named it "D++ Test Bot".
 3. Move on by click the "Bot" tab in the left-hand side of the screen. Now click the "Add Bot" button on the right and confirm that you want to add the bot to your application.
-
 \image html create_application_add_bot.png
-
 On the resulting screen, you’ll note a page with information regarding your new bot. You can edit your bot name, description, and avatar here if you want to. If you wish to read the message content from messages, you need to enable the message content intent in the "Privileged Gateway Intents" section.
-
 \image html create_application_bot_overview.png
-
 In this panel, you can get your bot token by clicking "Reset Token". A bot token looks like this: `OTAyOTMxODU1NTU1MzE3ODUw.YXlm0g.9oYCt-XHXVH_z9qAytzmVRzKWTg`
 
 \warning **Do not share this token** with anybody! If you ever somehow compromise your current bot token or see your bot in danger, you can regenerate the token in the panel.
 
-## Adding the bot to your server
+## Adding the Bot to Your Server
 
 Once you've created your bot in the discord developer portal, you may wonder:
+
 > Where is my bot now, I can't see him on my server?!
 
 That's because you've created a bot application, but it's not on any server right now. So, to invite the bot to your server, you must create an invitation URL.
 
-1. go again into the [Applications page](https://discord.com/developers/applications) and click on your bot.
+1. Go again into the [Applications page](https://discord.com/developers/applications) and click on your bot.
 2. Go to the "OAuth2" tab and click on the subpage "URL Generator".
 \image html create_application_navigate_to_url_generator.png
 3. Select the `bot` scope. If your bot uses slash commands, also select `applications.commands`. You can read more about scopes and which you need for your application [here](https://discord.com/developers/docs/topics/oauth2#shared-resources-oauth2-scopes).
 4. Choose the permissions required for your bot to function in the "Bot Permissions" section.
 5. Copy and paste the resulting URL in your browser. Choose a server to invite the bot to, and click "Authorize".
 
-
 \note For bots with elevated permissions, Discord enforces two-factor authentication on the bot owner's account when added to servers that have server-wide 2FA enabled.
 
 ## Troubleshooting
 
 - Stuck? You can find us on the [official discord server](https://discord.gg/dpp) - ask away! We don't bite!
-