Add some documentation comments

This is mostly setting a precedent, I hope that others will continue to
write docs for more headers.

Ref #218

1 files changed, 33 insertions, 7 deletions

diff --git a/include/commands.h b/include/commands.h
index f6777930..9135c670 100644
--- a/include/commands.h
+++ b/include/commands.h
@@ -5,29 +5,55 @@
 #include <wlc/wlc.h>
 #include "config.h"
 
-
-enum  cmd_status {
-	CMD_SUCCESS,
-	CMD_FAILURE, // was or at least could be executed
-	CMD_INVALID, // unknown or parse error
-	CMD_DEFER,
+/**
+ * Indicates the result of a command's execution.
+ */
+enum cmd_status {
+	CMD_SUCCESS, 		/**< The command was successful */
+	CMD_FAILURE,		/**< The command resulted in an error */
+	CMD_INVALID, 		/**< Unknown command or parser error */
+	CMD_DEFER,			/**< Command execution deferred */
 	// Config Blocks
 	CMD_BLOCK_END,
 	CMD_BLOCK_MODE,
 };
 
+/**
+ * Stores the result of executing a command.
+ */
 struct cmd_results {
 	enum cmd_status status;
 	char *input;
+	/**
+	 * Human friendly error message, or NULL on success
+	 */
 	char *error;
 };
 
+/**
+ * Parse and handles a command.
+ */
 struct cmd_results *handle_command(char *command);
-// Handles commands during config
+/**
+ * Parse and handles a command during config file loading.
+ *
+ * Do not use this under normal conditions.
+ */
 struct cmd_results *config_command(char *command);
 
+/**
+ * Allocates a cmd_results object.
+ */
 struct cmd_results *cmd_results_new(enum cmd_status status, const char* input, const char *error, ...);
+/**
+ * Frees a cmd_results object.
+ */
 void free_cmd_results(struct cmd_results *results);
+/**
+ * Serializes cmd_results to a JSON string.
+ *
+ * Free the JSON string later on.
+ */
 const char *cmd_results_to_json(struct cmd_results *results);
 
 void remove_view_from_scratchpad();