add comments

Author: braindigitalis

include/command_example/command.h

@@ -1,10 +1,29 @@
 #pragma once
 #include <dpp/dpp.h>
 
+/* Definition of our function callback for a command.
+ * As it uses std::function it can be a function pointer, a lambda, 
+ * or a std::bind to an object method.
+ * In this example we use function pointers.
+ * The command functions take two referneces, one to the dpp::cluster,
+ * and one to the slashcommand event struct.
+ */
 using command_function = std::function<void(dpp::cluster&, const dpp::slashcommand_t&)>;
 
+/**
+ * @brief A definition of a command for the command map
+ */
 struct command_definition {
+	/**
+	 * @brief Description of the command, must be lower case, no spaces.
+	 */
 	std::string description;
+	/**
+	 * @brief Callback function
+	 */
 	command_function function;
+	/**
+	 * @brief Parameters of the slash command
+	 */
 	std::vector<dpp::command_option> parameters = {};
-};
+};

include/command_example/commands/help.h

@@ -1,4 +1,8 @@
 #pragma once
 #include <dpp/dpp.h>
 
+/* This is a forward declaration so that command_example.cpp can #include
+ * this file, and find the handle_help function without including the
+ * entire source of the command.
+ */
 void handle_help(dpp::cluster& bot, const dpp::slashcommand_t& event);

include/command_example/commands/info.h

@@ -1,4 +1,8 @@
 #pragma once
 #include <dpp/dpp.h>
 
+/* This is a forward declaration so that command_example.cpp can #include
+ * this file, and find the handle_info function without including the
+ * entire source of the command.
+ */
 void handle_info(dpp::cluster& bot, const dpp::slashcommand_t& event);

include/command_example/commands/ping.h

@@ -1,4 +1,8 @@
 #pragma once
 #include <dpp/dpp.h>
 
+/* This is a forward declaration so that command_example.cpp can #include
+ * this file, and find the handle_ping function without including the
+ * entire source of the command.
+ */
 void handle_ping(dpp::cluster& bot, const dpp::slashcommand_t& event);

src/command_example.cpp

@@ -15,10 +15,20 @@
 
 using json = nlohmann::json;
 
+/* We define all our commands here.
+ * Each command has a name, a description, a command handler function and optionally a
+ * list of command parameters (each is of type dpp::command_option).
+ * To demonstrate this example we declare each of these handlers, e.g. handle_ping,
+ * handle_help and handle_info in separate files (see src/commands folder and
+ * include/commands folder) with individual header files. You can arrange this however
+ * you like, or you could even directly put a lambda into this map, but this would
+ * defeat the point of the example.
+ */
 std::map<std::string, command_definition> commands = {
 	{ "ping", { "A ping command", handle_ping }},
 	{ "help", {
 		"A help command", handle_help , { 
+			/* One optional string parameter */
 			{ dpp::command_option(dpp::co_string, "term", "Help term", false) },
 		}
 	}},
@@ -27,37 +37,47 @@ std::map<std::string, command_definition> commands = {
 
 int main()
 {
-	/* Setup the bot */
+	/* Setup the bot, reading token from config.json */
 	json configdocument;
 	std::ifstream configfile("../config.json");
 	configfile >> configdocument;
-
 	dpp::cluster bot(configdocument["token"]);
 
+	/* Default basic logger */
 	bot.on_log(dpp::utility::cout_logger());
 
+	/* In the on_ready we translate the commands map into a vector of dpp::slashcommand.
+	 * The vector of dpp::slashcommand is then passed to the command registration
+	 * method, dpp::cluster::global_bulk_command_create().
+	 */
 	bot.on_ready([&](const dpp::ready_t & event) {
-		std::vector<dpp::slashcommand> slash_commands;
-		for (auto & def : commands) {
-			dpp::slashcommand c;
-			c.set_name(def.first).set_description(def.second.description).set_application_id(bot.me.id);
-			for (auto & param : def.second.parameters) {
-				c.add_option(param);
+		if (dpp::run_once<struct bulk_register>()) {
+			std::vector<dpp::slashcommand> slash_commands;
+			for (auto & def : commands) {
+				dpp::slashcommand c;
+				c.set_name(def.first).
+				  set_description(def.second.description).
+				  set_application_id(bot.me.id);
+				c.options = def.second.parameters;
+				slash_commands.push_back(c);
 			}
-			slash_commands.push_back(c);
+			bot.global_bulk_command_create(slash_commands);
 		}
-		bot.global_bulk_command_create(slash_commands);
 	});
 
+	/* Handle slash commands */
 	bot.on_slashcommand([&bot](const dpp::slashcommand_t& event) {
 			dpp::command_interaction cmd_data = event.command.get_command_interaction();
-			/* Check for our /dialog command */
+			/* Check for commands that exist in our command map */
 			auto command_iter = commands.find(cmd_data.name);
 			if (command_iter != commands.end()) {
+				/* If we find a matching command, call its handler function,
+				 * passing in this event's information and the bot cluster
+				 * as references.
+				 */
 				command_iter->second.function(bot, event);
 			}
 	});
 
 	bot.start(false);
 }
-

src/commands/help.cpp

@@ -1,16 +1,26 @@
 #include "command_example/command.h"
 #include "command_example/commands/help.h"
 
+/* Example help command.
+ * Has an optional 'term' parameter that contains a help topic.
+ */
 void handle_help(dpp::cluster& bot, const dpp::slashcommand_t& event) {
 	auto parameter = event.get_parameter("term");
+
+	/* Check to see if the parameter is provided by the user */
 	if (std::holds_alternative<std::string>(parameter)) {
+
+		/* If it is, get it and check what's in it */
 		std::string search_term = std::get<std::string>(parameter);
 		if (search_term == "ping") {
+			/* Some reply to help for PING */
 			event.reply("This help left useless as an exercise for the developer.");
 		} else {
+			/* Anything, something, so long as the bot replies. */
 			event.reply("This message intentionally left blank. 🤪");
 		}
 	}
+	/* Help reply */
 	event.reply(
 		dpp::message().add_embed(
 			dpp::embed().
@@ -22,4 +32,4 @@ void handle_help(dpp::cluster& bot, const dpp::slashcommand_t& event) {
 			add_field("/ping", "Pong?")
 		)
 	);
-}
+}

src/commands/info.cpp

@@ -1,6 +1,8 @@
 #include "command_example/command.h"
 #include "command_example/commands/info.h"
 
+/* Example info command
+ */
 void handle_info(dpp::cluster& bot, const dpp::slashcommand_t& event) {
 	event.reply(
 		dpp::message().add_embed(

src/commands/ping.cpp

@@ -2,14 +2,22 @@
 #include "command_example/commands/ping.h"
 #include <dpp/fmt/format.h>
 
+/* Example ping command
+ * Calculates rest + websocket ping
+ */
 void handle_ping(dpp::cluster& bot, const dpp::slashcommand_t& event) {
+	/* Get websocket ping of first shard */
 	float ws_ping = bot.get_shard(0)->websocket_ping;
+
+	/* Ping reply */
 	event.reply(
 		dpp::message().add_embed(
 			dpp::embed().
 			set_color(dpp::colors::yellow).
 			set_title("PONG!").
-			set_description(fmt::format("Ping is: {0:.02f} ms", (bot.rest_ping + ws_ping) * 1000))
+			set_description(
+				fmt::format("Ping is: {0:.02f} ms", (bot.rest_ping + ws_ping) * 1000)
+			)
 		)
 	);
 }