📝 Clean up the documentation

* Resolves bunch of unrelated documentation issues * Wrong capitalisation of headers and brands * Wrong indentation of code examples * Various typos, missing Oxford commas, bad style, or typography * Examples didn't follow Style Guidelines in many places * Tries to slim down on unneeded newlines * Bunch of files have been wrongly named or wrongly placed * Attempt to update some outdated details * Overall there are other things the would deserve some work but that felt too ambitious for this already huge changeset
brainboxdotcc · Aug 29, 2023 · f3943e2 · f3943e2
1 parent df5eaa0
commit f3943e2
Show file tree

Hide file tree

Showing 77 changed files with 1,633 additions and 1,707 deletions.
diff --git a/.github/ISSUE_TEMPLATE/bug_report.md b/.github/ISSUE_TEMPLATE/bug_report.md
@@ -1,33 +1,33 @@
 ---
-name: Bug report
+name: Bug Report
 about: Create a report to help us improve
 title: ''
 labels: bug
 assignees: braindigitalis
 
 ---
 
-**Git commit reference**
+**Git Commit Reference**
 The git commit reference of the version you are using, obtainable via `git show -s --format="%H"`
 
-**Describe the bug**
+**Describe the Bug**
 A clear and concise description of what the bug is.
 
 **To Reproduce**
-Steps to reproduce the behavior:
+Steps to reproduce the behaviour:
 1. Issue the method call 'X'
 2. Retrieve returned value 'Y'
 3. Returned value not in the range 'A..B'
 
-**Expected behavior**
+**Expected Behaviour**
 A clear and concise description of what you expected to happen.
 
 **Screenshots**
 If applicable, add screenshots to help explain your problem.
 
-**System Details:**
+**System Details**
  - OS: [e.g. Debian Bullseye]
  - Discord Client used for testing [mobile, desktop, web]
 
-**Additional context**
-Add any other context about the problem here.
+**Additional Context**
+Add any other context about the problem here.
diff --git a/.github/ISSUE_TEMPLATE/feature_request.md b/.github/ISSUE_TEMPLATE/feature_request.md
@@ -1,5 +1,5 @@
 ---
-name: Feature request
+name: Feature Request
 about: Suggest an idea for this project
 title: ''
 labels: ''
@@ -8,7 +8,7 @@ assignees: ''
 ---
 
 **Is your feature request related to a problem? Please describe.**
-A clear and concise description of what the problem is. Ex. I'm always frustrated when [...]
+A clear and concise description of what the problem is. E.g. I'm always frustrated when […]
 
 **Describe the solution you'd like**
 A clear and concise description of what you want to happen.
@@ -17,4 +17,4 @@ A clear and concise description of what you want to happen.
 A clear and concise description of any alternative solutions or features you've considered.
 
 **Additional context**
-Add any other context or screenshots about the feature request here.
+Add any other context or screenshots about the feature request here.
diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md
@@ -1,8 +1,9 @@
+<Your PR description comes here>
+
 - [ ] My pull request is made against the `dev` branch.
 - [ ] I have ensured that the changed library can be built on your target system. I did not introduce any platform-specific code.
-- [ ] I have ensured that all methods and functions are **fully documented** using doxygen style comments.
-- [ ] I tested my commits, by adding a test case to the unit tests if needed
+- [ ] I have ensured that all methods and functions are **fully documented** using Doxygen style comments.
+- [ ] I tested my commits, by adding a test case to the unit tests if needed.
 - [ ] I have ensured that I did not break any existing API calls.
-- [ ] My code follows the [coding style guide](https://dpp.dev/coding-standards.html) (if you are not sure, match the code style of existing files including indent style etc).
-- [ ] I have not built my pull request using AI, a static analysis tool or similar without any human oversight. Where I have generated this pull request using a tool, I have justified why this is needed.
-
+- [ ] My code follows the [coding style guide](https://dpp.dev/coding-standards.html) (if you are not sure, match the code style of existing files including indent style etc.).
+- [ ] I have not built my pull request using AI, a static analysis tool, or similar without any human oversight. Where I have generated this pull request using a tool, I have justified why this is needed.
diff --git a/CODE_OF_CONDUCT.md b/CODE_OF_CONDUCT.md
@@ -1,4 +1,3 @@
-
 # Contributor Covenant Code of Conduct
 
 ## Our Pledge
@@ -60,8 +59,9 @@ representative at an online or offline event.
 ## Enforcement
 
 Instances of abusive, harassing, or otherwise unacceptable behavior may be
-reported to the community leaders responsible for enforcement in the
-[Discord][discord] server.
+reported to the community leaders responsible for enforcement at
+[the official Discord server](https://discord.gg/dpp) or sent via DM to `@brain`
+for discreet treatment.
 All complaints will be reviewed and investigated promptly and fairly.
 
 All community leaders are obligated to respect the privacy and security of the
@@ -126,9 +126,8 @@ For answers to common questions about this code of conduct, see the FAQ at
 [https://www.contributor-covenant.org/faq][FAQ]. Translations are available at
 [https://www.contributor-covenant.org/translations][translations].
 
-[discord]: https://discord.gg/dpp
 [homepage]: https://www.contributor-covenant.org
 [v2.1]: https://www.contributor-covenant.org/version/2/1/code_of_conduct.html
 [Mozilla CoC]: https://github.com/mozilla/diversity
 [FAQ]: https://www.contributor-covenant.org/faq
-[translations]: https://www.contributor-covenant.org/translations
+[translations]: https://www.contributor-covenant.org/translations
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -5,14 +5,10 @@ When contributing to this repository, please do not feel intimidated! We welcome
 ## Pull Request Process
 
 1. Pull requests should be made against the `dev` branch.
-2. Ensure that the changed library can be built on your target system. Do not introduce any platform-
-   specific code.
+2. Ensure that the changed library can be built on your target system. Do not introduce any platform specific code.
 3. Ensure that all methods and functions you add are **fully documented** using doxygen style comments.
-4. Test your commit! Make a simple single-file test bot to demonstrate the change, include this with the PR 
-   as an attached file on a comment, so we can test and see how it works.
+4. Test your commit! Make a simple single-file test bot to demonstrate the change, include this with the PR as an attached file on a comment, so we can test and see how it works.
 5. Ensure that you do not break any existing API calls without discussing on Discord first!
-6. Be sure to follow the coding style guide (if you are not sure, match the code style of existing files
-   including indent style etc).
-7. Your PR must pass the CI actions before being allowed to be merged. Our PR actions check that the
-   build will compile on various platforms before release and makes precompiled versions of the library.
-8. Automated changes e.g. via grammarly or a static analysis tool will not usually be accepted into the code without proper thought out justification (by a human being, not an AI or an App) as to why the changes are required. Generally a PR should do more than fix a single spelling error for example as this just takes precious time for something which could be resolved a direct commit to the dev branch.
+6. Be sure to follow the coding style guide (if you are not sure, match the code style of existing files including indent style etc.).
+7. Your PR must pass the CI actions before being allowed to be merged. Our PR actions check that the build will compile on various platforms before release and make precompiled versions of the library.
+8. Automated changes e.g. via Grammarly or a static analysis tool will not usually be accepted into the code without proper thought out justification (by a human being, not an AI or an App) as to why the changes are required. Generally a PR should do more than fix a single spelling error for example as this just takes precious time for something which could have been resolved by a direct commit to the dev branch.
diff --git a/LICENSE b/LICENSE
@@ -186,7 +186,7 @@
       same "printed page" as the copyright notice for easier
       identification within third-party archives.
 
-   Copyright 2021 Craig Edwards and D++ Contributors
+   Copyright 2021-2023 Craig Edwards and D++ Contributors
 
    Licensed under the Apache License, Version 2.0 (the "License");
    you may not use this file except in compliance with the License.
@@ -198,4 +198,4 @@
    distributed under the License is distributed on an "AS IS" BASIS,
    WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
    See the License for the specific language governing permissions and
-   limitations under the License.
+   limitations under the License.
diff --git a/README.md b/README.md
@@ -15,10 +15,9 @@
 
 <hr />
 
-
 D++ is a lightweight and efficient library for **Discord** written in **modern C++**, covering as much of the API specification as possible with an **incredibly small memory footprint** even when caching large amounts of data.
 
-### Library features:
+### Library Features
 
 * Support for Discord API v10
 * Really small memory footprint
@@ -29,7 +28,7 @@ D++ is a lightweight and efficient library for **Discord** written in **modern C
 * [Voice support](https://dpp.dev/soundboard.html) (sending **and** receiving audio)
 * The entire Discord API is available for use in the library
 * Stable [Windows support](https://dpp.dev/buildwindows.html)
-* Ready-made compiled packages for Windows, Raspberry Pi (ARM64/ARM7/ARMv6), Debian x86/x64 and RPM based distributions
+* Ready-made compiled packages for Windows, Raspberry Pi (ARM64/ARM7/ARMv6), Debian x86/x64, and RPM based distributions
 * Highly scalable for large amounts of guilds and users
 
 Want to help? Drop me a line or send a PR.
@@ -46,28 +45,29 @@ The documentation is constantly evolving and improving, generated from the code
 
 This is a simple ping-pong example using slash commands.
 
-```c++
+```cpp
 #include <dpp/dpp.h>
 #include <cstdlib>
- 
+
 int main() {
-    dpp::cluster bot(std::getenv("BOT_TOKEN"));
-
-    bot.on_slashcommand([](auto event) {
-         if (event.command.get_command_name() == "ping") {
-             event.reply("Pong!");
-         }
-    });
-
-    bot.on_ready([&bot](auto event) {
-        if (dpp::run_once<struct register_bot_commands>()) {
-            bot.global_command_create(
-                dpp::slashcommand("ping", "Ping pong!", bot.me.id)
-            );
-        }
-    });
-
-    bot.start(dpp::st_wait);
+	dpp::cluster bot(std::getenv("BOT_TOKEN"));
+
+	bot.on_slashcommand([](auto event) {
+		if (event.command.get_command_name() == "ping") {
+			event.reply("Pong!");
+		}
+	});
+
+	bot.on_ready([&bot](auto event) {
+		if (dpp::run_once<struct register_bot_commands>()) {
+			bot.global_command_create(
+				dpp::slashcommand("ping", "Ping pong!", bot.me.id)
+			);
+		}
+	});
+
+	bot.start(dpp::st_wait);
+	return 0;
 }
 ```
 
@@ -76,18 +76,23 @@ You can find more examples in our [example page](https://dpp.dev/md_docpages_03_
 ## 💻 Supported Systems
 
 ### Linux
+
 The library runs ideally on **Linux**.
 
-### Mac OS X and FreeBSD
-The library is well-functional and stable on **Mac OS X** and **FreeBSD** too.
+### macOS and FreeBSD
+
+The library is well-functional and stable on **macOS** and **FreeBSD** too.
 
 ### Raspberry Pi
+
 For running your bot on a **Raspberry Pi**, we offer a prebuilt .deb package for ARM64, ARM6, and ARM7 so that you do not have to wait for it to compile.
 
 ### Windows
+
 **Windows** is well-supported with ready-made compiled DLL and LIB files, please check out our [Windows Bot Template repository](https://github.com/brainboxdotcc/windows-bot-template). The Windows Bot repository can be cloned and integrated immediately into any Visual Studio 2019 and 2022 project in a matter of minutes.
 
 ### Other OS
+
 The library should work fine on other operating systems as well, and if you run a D++ bot on something not listed here, please let us know!
 
 ## 🔰 Getting Started
@@ -106,15 +111,13 @@ For frequently asked questions and their answers, please visit our [FAQ page](ht
 
 ## 🤝 Contributing
 
-Contributions, issues and feature requests are welcome. After cloning and setting up project locally, you can just submit 
-a PR to this repo and it will be deployed once it's accepted.
+Contributions, issues and feature requests are welcome. After cloning and setting up a project locally, you can just submit a PR to this repo and it will be deployed once it's accepted.
 
 Please read the [D++ Code Style Guide](https://dpp.dev/coding-standards.html) for more information on how we format pull requests.
 
 ## 💬 Get in touch
 
-If you have various suggestions, questions or want to discuss things with our community, [Join our discord server](https://discord.gg/dpp)!
-Make a humorous reference to brains in your nickname to get access to a secret brain cult channel! :)
+If you have various suggestions, questions or want to discuss things with our community, [Join our discord server](https://discord.gg/dpp)! Make a humorous reference to brains in your nickname to get access to a secret brain cult channel! :)
 
 [![Discord](https://img.shields.io/discord/825407338755653642?style=flat)](https://discord.gg/dpp)
 
@@ -125,26 +128,30 @@ We love people's support in growing and improving. Be sure to leave a ⭐️ if
 ## 📂 Dependencies
 
 ### Build requirements
-* [cmake](https://cmake.org/) (version 3.13+)
+
+* [CMake](https://cmake.org/) (version 3.13+)
 * A supported C++ compiler from the list below
 
 ### Supported compilers
+
 * [g++](https://gcc.gnu.org) (version 8 or higher)
-* [clang](https://clang.llvm.org/)
+* [Clang](https://clang.llvm.org/)
 * AppleClang (12.0 or higher)
-* Microsoft Visual Studio 2019 or 2022 (16.x/17.x)
-* [mingw-w64](https://www.mingw-w64.org/) (gcc version 8 or higher)
+* [Microsoft Visual Studio 2019 or 2022](https://visualstudio.microsoft.com/downloads/) (16.x/17.x)
 
 Other compilers may work (either newer versions of those listed above, or different compilers entirely) but have not been tested by us.
 
 ### External Dependencies (You must install these)
+
 * [OpenSSL](https://openssl.org/) (whichever `-dev` package comes with your OS)
 * [zlib](https://zlib.net) (whichever `-dev` package comes with your OS)
 
 #### Optional Dependencies
+
 For voice support you require both of:
 * [LibOpus](https://www.opus-codec.org)
 * [libsodium](https://github.com/jedisct1/libsodium)
 
 ### Included Dependencies (Packaged with the library)
-* [nlohmann::json](https://github.com/nlohmann/json)
+
+* [nlohmann::json](https://github.com/nlohmann/json)
diff --git a/SECURITY.md b/SECURITY.md
@@ -10,5 +10,4 @@
 
 ## Reporting a Vulnerability
 
-To report a vulnerability please contact the development team confidentially on Discord by contacting `@brain` via a DM on https://discord.gg/dpp - We will discuss via a group chat if necessary and action
-the fix. Vulnerabilties are actioned and fixed within a 30 day window. Once the fix has been put into a release version, the vulnerability will be disclosed to the public.
+To report a vulnerability please contact the development team confidentially on Discord by contacting `@brain` via a DM on https://discord.gg/dpp - We will discuss via a group chat if necessary and action the fix. Vulnerabilities are actioned and fixed within a 30 day window. Once the fix has been put into a release version, the vulnerability will be disclosed to the public.