style: refactored comments in several files to follow standard (#975)

include/dpp/automod.h

@@ -38,10 +38,12 @@ enum automod_preset_type : uint8_t {
 	 * @brief Strong swearing
 	 */
 	amod_preset_profanity = 1,
+
 	/**
 	 * @brief Sexual phrases and words
 	 */
 	amod_preset_sexual_content = 2,
+
 	/**
 	 * @brief Racial and other slurs, hate speech
 	 */
@@ -57,10 +59,12 @@ enum automod_action_type : uint8_t {
 	 * A custom explanation can be specified and shown to members whenever their message is blocked
 	 */
 	amod_action_block_message = 1,
+
 	/**
 	 * @brief Send an alert to a given channel
 	 */
 	amod_action_send_alert = 2,
+
 	/**
 	 * @brief timeout the user
 	 * @note Can only be set up for rules with trigger types of dpp::amod_type_keyword and dpp::amod_type_mention_spam
@@ -86,19 +90,23 @@ enum automod_trigger_type : uint8_t {
 	 * @brief Check if content contains words from a user defined list of keywords (max 6 of this type per guild)
 	 */
 	amod_type_keyword = 1,
+
 	/**
 	 * @brief Harmful/malware links
 	 * @deprecated Removed by Discord
 	 */
 	amod_type_harmful_link = 2,
+
 	/**
 	 * @brief Check if content represents generic spam (max 1 of this type per guild)
 	 */
 	amod_type_spam = 3,
+
 	/**
 	 * @brief Check if content contains words from discord pre-defined wordsets (max 1 of this type per guild)
 	 */
 	amod_type_keyword_preset = 4,
+
 	/**
 	 * @brief Check if content contains more mentions than allowed (max 1 of this type per guild)
 	 */
@@ -141,31 +149,31 @@ struct DPP_EXPORT automod_metadata : public json_interface<automod_metadata> {
 	 * Prefix - word must start with the keyword
 	 *
 	 * | keyword  | matches                             |
-     * |----------|-------------------------------------|
-     * | cat*     | <u><b>cat</b></u>ch, <u><b>Cat</b></u>apult, <u><b>CAt</b></u>tLE |
-     * | the mat* | <u><b>the mat</b></u>rix                      |
-     *
-     * Suffix - word must end with the keyword
-     *
-     * | keyword  | matches                  |
-     * |----------|--------------------------|
-     * | *cat     | wild<u><b>cat</b></u>, copy<u><b>Cat</b></u> |
-     * | *the mat | brea<u><b>the mat</b></u>          |
-     *
-     * Anywhere - keyword can appear anywhere in the content
-     *
-     * | keyword   | matches                     |
-     * |-----------|-----------------------------|
-     * | \*cat*     | lo<u><b>cat</b></u>ion, edu<u><b>Cat</b></u>ion |
-     * | \*the mat* | brea<u><b>the mat</b></u>ter          |
-     *
-     * Whole Word - keyword is a full word or phrase and must be surrounded by whitespace at the beginning and end
-     *
-     * | keyword | matches     |
-     * |---------|-------------|
-     * | cat     | <u><b>Cat</b></u>     |
-     * | the mat | <u><b>the mat</b></u> |
-     *
+     	 * |----------|-------------------------------------|
+     	 * | cat*     | <u><b>cat</b></u>ch, <u><b>Cat</b></u>apult, <u><b>CAt</b></u>tLE |
+     	 * | the mat* | <u><b>the mat</b></u>rix                      |
+     	 *
+     	 * Suffix - word must end with the keyword
+     	 *
+     	 * | keyword  | matches                  |
+     	 * |----------|--------------------------|
+     	 * | *cat     | wild<u><b>cat</b></u>, copy<u><b>Cat</b></u> |
+     	 * | *the mat | brea<u><b>the mat</b></u>          |
+     	 *
+     	 * Anywhere - keyword can appear anywhere in the content
+    	 *
+    	 * | keyword   | matches                     |
+    	 * |-----------|-----------------------------|
+    	 * | \*cat*     | lo<u><b>cat</b></u>ion, edu<u><b>Cat</b></u>ion |
+     	 * | \*the mat* | brea<u><b>the mat</b></u>ter          |
+     	 *
+    	 * Whole Word - keyword is a full word or phrase and must be surrounded by whitespace at the beginning and end
+    	 *
+    	 * | keyword | matches     |
+    	 * |---------|-------------|
+    	 * | cat     | <u><b>Cat</b></u>     |
+    	 * | the mat | <u><b>the mat</b></u> |
+    	 *
 	 */
 	std::vector<std::string> keywords;
 
@@ -196,31 +204,31 @@ struct DPP_EXPORT automod_metadata : public json_interface<automod_metadata> {
 	 * Prefix - word must start with the keyword
 	 *
 	 * | keyword  | matches                             |
-     * |----------|-------------------------------------|
-     * | cat*     | <u><b>cat</b></u>ch, <u><b>Cat</b></u>apult, <u><b>CAt</b></u>tLE |
-     * | the mat* | <u><b>the mat</b></u>rix                      |
-     *
-     * Suffix - word must end with the keyword
-     *
-     * | keyword  | matches                  |
-     * |----------|--------------------------|
-     * | *cat     | wild<u><b>cat</b></u>, copy<u><b>Cat</b></u> |
-     * | *the mat | brea<u><b>the mat</b></u>          |
-     *
-     * Anywhere - keyword can appear anywhere in the content
-     *
-     * | keyword   | matches                     |
-     * |-----------|-----------------------------|
-     * | \*cat*     | lo<u><b>cat</b></u>ion, edu<u><b>Cat</b></u>ion |
-     * | \*the mat* | brea<u><b>the mat</b></u>ter          |
-     *
-     * Whole Word - keyword is a full word or phrase and must be surrounded by whitespace at the beginning and end
-     *
-     * | keyword | matches     |
-     * |---------|-------------|
-     * | cat     | <u><b>Cat</b></u>     |
-     * | the mat | <u><b>the mat</b></u> |
-     *
+     	 * |----------|-------------------------------------|
+     	 * | cat*     | <u><b>cat</b></u>ch, <u><b>Cat</b></u>apult, <u><b>CAt</b></u>tLE |
+     	 * | the mat* | <u><b>the mat</b></u>rix                      |
+     	 *
+     	 * Suffix - word must end with the keyword
+     	 *
+     	 * | keyword  | matches                  |
+     	 * |----------|--------------------------|
+     	 * | *cat     | wild<u><b>cat</b></u>, copy<u><b>Cat</b></u> |
+     	 * | *the mat | brea<u><b>the mat</b></u>          |
+     	 *
+     	 * Anywhere - keyword can appear anywhere in the content
+     	 *
+     	 * | keyword   | matches                     |
+     	 * |-----------|-----------------------------|
+     	 * | \*cat*     | lo<u><b>cat</b></u>ion, edu<u><b>Cat</b></u>ion |
+     	 * | \*the mat* | brea<u><b>the mat</b></u>ter          |
+     	 *
+     	 * Whole Word - keyword is a full word or phrase and must be surrounded by whitespace at the beginning and end
+     	 *
+     	 * | keyword | matches     |
+     	 * |---------|-------------|
+     	 * | cat     | <u><b>Cat</b></u>     |
+     	 * | the mat | <u><b>the mat</b></u> |
+     	 *
 	 */
 	std::vector<std::string> allow_list;
 
@@ -326,42 +334,52 @@ class DPP_EXPORT automod_rule : public managed, public json_interface<automod_ru
 	 * @brief the id of this rule
 	 */
 	snowflake       	id;
+
 	/**
 	 * @brief the guild which this rule belongs to
 	 */
 	snowflake       	guild_id;
+
 	/**
 	 * @brief the rule name
 	 */
 	std::string     	name;
+
 	/**
 	 * @brief The user which first created this rule
 	 */
 	snowflake       	creator_id;
+
 	/**
 	 * @brief The rule event type
 	 */
 	automod_event_type	event_type;
+
 	/**
 	 * @brief The rule trigger type
 	 */
 	automod_trigger_type	trigger_type;
+
 	/**
 	 * @brief The rule trigger metadata
 	 */
 	automod_metadata	trigger_metadata;
+
 	/**
 	 * @brief the actions which will execute when the rule is triggered
 	 */
 	std::vector<automod_action> actions;
+
 	/**
 	 * @brief Whether the rule is enabled
 	 */
 	bool			enabled;
+
 	/**
 	 * @brief the role ids that should not be affected by the rule (Maximum of 20)
 	 */
 	std::vector<snowflake>	exempt_roles;
+
 	/**
 	 * @brief the channel ids that should not be affected by the rule (Maximum of 50)
 	 */

include/dpp/ban.h

@@ -44,9 +44,14 @@ class DPP_EXPORT ban : public json_interface<ban> {
 	ban& fill_from_json_impl(nlohmann::json* j);
 
 public:
-	/** The ban reason */
+	/**
+	 * @brief The ban reason.
+	 */
 	std::string reason;
-	/** User ID the ban applies to */
+
+	/**
+	 * @brief User ID the ban applies to.
+	 */
 	snowflake user_id;
 
 	/** Constructor */
@@ -57,7 +62,7 @@ class DPP_EXPORT ban : public json_interface<ban> {
 };
 
 /**
- * A group of bans. The key is the user ID
+ * @brief A group of bans. The key is the user ID.
  */
 typedef std::unordered_map<snowflake, ban> ban_map;
 

include/dpp/cache.h

@@ -65,7 +65,7 @@ template<class T> class cache {
 	/**
 	 * @brief Construct a new cache object.
 	 * 
-	 * Caches must contain classes derived from dpp::managed.
+	 * @note Caches must contain classes derived from dpp::managed.
 	 */
 	cache() {
 		cache_map = new std::unordered_map<snowflake, T*>;
@@ -255,7 +255,8 @@ template<class T> class cache {
 
 };
 
-/** Run garbage collection across all caches removing deleted items
+/**
+ * Run garbage collection across all caches removing deleted items
  * that have been deleted over 60 seconds ago.
  */
 void DPP_EXPORT garbage_collection();

include/dpp/coro/async.h

@@ -56,39 +56,54 @@ namespace async {
  * @brief Represents the step an std::async is at.
  */
 enum class state_t {
-	sent, /* Request was sent but not co_await-ed. handle is nullptr, result_storage is not constructed */
-	waiting, /* Request was co_await-ed. handle is valid, result_storage is not constructed */
-	done, /* Request was completed. handle is unknown, result_storage is valid */
-	dangling /* Request was never co_await-ed. */
+	/**
+	 * @brief Request was sent but not co_await-ed. handle is nullptr, result_storage is not constructed.
+	 */
+	sent,
+
+	/**
+	 * @brief Request was co_await-ed. handle is valid, result_storage is not constructed.
+	 */
+	waiting,
+
+	/**
+	 * @brief Request was completed. handle is unknown, result_storage is valid.
+	 */
+	done,
+
+	/**
+	 * @brief Request was never co_await-ed.
+	 */
+	dangling
 };
 
 /**
-	* @brief State of the async and its callback.
-	*
-	* Defined outside of dpp::async because this seems to work better with Intellisense.
-	*/
+ * @brief State of the async and its callback.
+ *
+ * Defined outside of dpp::async because this seems to work better with Intellisense.
+ */
 template <typename R>
 struct async_callback_data {
 	/**
-		* @brief Number of references to this callback state.
-		*/
+	 * @brief Number of references to this callback state.
+	 */
 	std::atomic<int> ref_count{1};
 
 	/**
-		* @brief State of the awaitable and the API callback
-		*/
+	 * @brief State of the awaitable and the API callback
+	 */
 	std::atomic<state_t> state = state_t::sent;
 
 	/**
-		* @brief The stored result of the API call, stored as an array of bytes to directly construct in place
-		*/
+	 * @brief The stored result of the API call, stored as an array of bytes to directly construct in place
+	 */
 	alignas(R) std::array<std::byte, sizeof(R)> result_storage;
 
 	/**
-		* @brief Handle to the coroutine co_await-ing on this API call
-		*
-		* @see <a href="https://en.cppreference.com/w/cpp/coroutine/coroutine_handle">std::coroutine_handle</a>
-		*/
+	 * @brief Handle to the coroutine co_await-ing on this API call
+	 *
+	 * @see <a href="https://en.cppreference.com/w/cpp/coroutine/coroutine_handle">std::coroutine_handle</a>
+	 */
 	std_coroutine::coroutine_handle<> coro_handle = nullptr;
 
 	/**
@@ -374,7 +389,8 @@ class async_base {
 
 struct confirmation_callback_t;
 
-/** @class async async.h coro/async.h
+/**
+ * @class async async.h coro/async.h
  * @brief A co_await-able object handling an API call in parallel with the caller.
  *
  * This class is the return type of the dpp::cluster::co_* methods, but it can also be created manually to wrap any async call.

include/dpp/coro/coro.h

@@ -45,17 +45,17 @@ namespace std {
 namespace dpp {
 
 /**
-	* @brief Implementation details for internal use only.
-	*
-	* @attention This is only meant to be used by D++ internally. Support will not be given regarding the facilities in this namespace.
-	*/
+ * @brief Implementation details for internal use only.
+ *
+ * @attention This is only meant to be used by D++ internally. Support will not be given regarding the facilities in this namespace.
+ */
 namespace detail {
 #ifdef _DOXYGEN_
 /**
-	* @brief Alias for either std or std::experimental depending on compiler and library. Used by coroutine implementation.
-	*
-	* @todo Remove and use std when all supported libraries have coroutines in it
-	*/
+ * @brief Alias for either std or std::experimental depending on compiler and library. Used by coroutine implementation.
+ *
+ * @todo Remove and use std when all supported libraries have coroutines in it
+ */
 namespace std_coroutine {}
 #else
 #  ifdef STDCORO_EXPERIMENTAL_NAMESPACE

include/dpp/coro/coroutine.h

@@ -51,8 +51,8 @@ struct promise_t;
 
 template <typename R>
 /**
-	* @brief Alias for the handle_t of a coroutine.
-	*/
+ * @brief Alias for the handle_t of a coroutine.
+ */
 using handle_t = std_coroutine::coroutine_handle<promise_t<R>>;
 
 /**
@@ -188,7 +188,8 @@ class coroutine_base {
 
 } // namespace detail
 
-/** @class coroutine coroutine.h coro/coroutine.h
+/**
+ * @class coroutine coroutine.h coro/coroutine.h
  * @brief Base type for a coroutine, starts on co_await.
  *
  * @warning - This feature is EXPERIMENTAL. The API may change at any time and there may be bugs.