Add some documentation comments

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

Ref #218

3 files changed, 224 insertions, 46 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();
diff --git a/include/config.h b/include/config.h
index 636d3ec0..8338033c 100644
--- a/include/config.h
+++ b/include/config.h
@@ -8,22 +8,36 @@
 #include "layout.h"
 #include "container.h"
 
+/**
+ * Describes a variable created via the `set` command.
+ */
 struct sway_variable {
         char *name;
         char *value;
 };
 
+/**
+ * A key binding and an associated command.
+ */
 struct sway_binding {
         list_t *keys;
         uint32_t modifiers;
         char *command;
 };
 
+/**
+ * A "mode" of keybindings created via the `mode` command.
+ */
 struct sway_mode {
         char *name;
         list_t *bindings;
 };
 
+/**
+ * Size and position configuration for a particular output.
+ *
+ * This is set via the `output` command.
+ */
 struct output_config {
         char *name;
         bool enabled;
@@ -31,11 +45,19 @@ struct output_config {
         int x, y;
 };
 
+/**
+ * Maps a workspace name to an output name.
+ *
+ * Set via `workspace <x> output <y>`
+ */
 struct workspace_output {
         char *output;
         char *workspace;
 };
 
+/**
+ * The configuration struct. The result of loading a config file.
+ */
 struct sway_config {
         list_t *symbols;
         list_t *modes;
@@ -62,12 +84,24 @@ struct sway_config {
         int gaps_outer;
 };
 
+/**
+ * Loads the config from the given path.
+ */
 bool load_config(const char *file);
+/** Reads the config from the given FILE.
+ */
 bool read_config(FILE *file, bool is_active);
+/**
+ * Does variable replacement for a string based on the config's currently loaded variables.
+ */
 char *do_var_replacement(char *str);
-// Setup output container by applying given config
+/** Sets up a WLC output handle based on a given output_config.
+ */
 void apply_output_config(struct output_config *oc, swayc_t *output);
 
+/**
+ * Global config singleton.
+ */
 extern struct sway_config *config;
 
 #endif
diff --git a/include/container.h b/include/container.h
index d5eb27c1..8c54ee24 100644
--- a/include/container.h
+++ b/include/container.h
@@ -5,42 +5,72 @@ typedef struct sway_container swayc_t;
 
 #include "layout.h"
 
-enum swayc_types{
-        C_ROOT,
-        C_OUTPUT,
-        C_WORKSPACE,
-        C_CONTAINER,
-        C_VIEW,
+/**
+ * Different kinds of containers.
+ * 
+ * This enum is in order. A container will never be inside of a container below
+ * it on this list.
+ */
+enum swayc_types {
+        C_ROOT,                         /**< The root container. Only one of these ever exists. */
+        C_OUTPUT,                       /**< An output (aka monitor, head, etc). */
+        C_WORKSPACE,            /**< A workspace. */
+        C_CONTAINER,            /**< A manually created container. */
+        C_VIEW,                         /**< A view (aka window). */
         // Keep last
         C_TYPES,
 };
 
-
-enum swayc_layouts{
-        L_NONE,
+/**
+ * Different ways to arrange a container.
+ */
+enum swayc_layouts {
+        L_NONE,                         /**< Used for containers that have no layout (views, root) */
         L_HORIZ,
         L_VERT,
         L_STACKED,
         L_TABBED,
-        L_FLOATING,
+        L_FLOATING,                     /**< A psuedo-container, removed from the tree, to hold floating windows */
         // Keep last
         L_LAYOUTS,
 };
 
+/**
+ * Stores information about a container.
+ *
+ * The tree is made of these. Views are containers that cannot have children.
+ */
 struct sway_container {
+        /**
+         * If this container maps to a WLC object, this is set to that object's
+         * handle. Otherwise, NULL.
+         */
         wlc_handle handle;
 
         enum swayc_types type;
         enum swayc_layouts layout;
 
-        // Not including borders or margins
+        /**
+         * Width and height of this container, without borders or gaps.
+         */
         double width, height;
 
-        // Used for setting floating geometry
+        /**
+         * Views may request geometry, which is stored in this and ignored until
+         * the views are floated.
+         */
         int desired_width, desired_height;
 
+        /**
+         * The coordinates that this view appear at, relative to the output they
+         * are located on.
+         */
         double x, y;
 
+        /**
+         * False if this view is invisible. It could be in the scratchpad or on a
+         * workspace that is not shown.
+         */
         bool visible;
         bool is_floating;
         bool is_focused;
@@ -50,9 +80,18 @@ struct sway_container {
         int gaps;
 
         list_t *children;
+        /**
+         * Children of this container that are floated.
+         */
         list_t *floating;
 
+        /**
+         * The parent of this container. NULL for the root container.
+         */
         struct sway_container *parent;
+        /**
+         * Which of this container's children has focus.
+         */
         struct sway_container *focused;
 };
 
@@ -60,68 +99,147 @@ enum visibility_mask {
         VISIBLE = true
 } visible;
 
-// Container Creation
-
+/**
+ * Allocates a new output container.
+ */
 swayc_t *new_output(wlc_handle handle);
+/**
+ * Allocates a new workspace container.
+ */
 swayc_t *new_workspace(swayc_t *output, const char *name);
-// Creates container Around child (parent child) -> (parent (container child))
+/**
+ * Allocates a new container and places a child into it.
+ *
+ * This is used from the split command, which creates a new container with the
+ * requested layout and replaces the focused container in the tree with the new
+ * one. Then the removed container is added as a child of the new container.
+ */
 swayc_t *new_container(swayc_t *child, enum swayc_layouts layout);
-// Creates view as a sibling of current focused container, or as child of a workspace
+/**
+ * Allocates a new view container.
+ *
+ * Pass in a sibling view, or a workspace to become this container's parent.
+ */
 swayc_t *new_view(swayc_t *sibling, wlc_handle handle);
-// Creates view as a new floating view which is in the active workspace
+/**
+ * Allocates a new floating view in the active workspace.
+ */
 swayc_t *new_floating_view(wlc_handle handle);
 
-// Container Destroying
-
+/**
+ * Frees an output's container.
+ */
 swayc_t *destroy_output(swayc_t *output);
-// Destroys workspace if empty and returns parent pointer, else returns NULL
+/**
+ * Destroys a workspace container and returns the parent pointer, or NULL.
+ */
 swayc_t *destroy_workspace(swayc_t *workspace);
-// Destroyes container and all parent container if they are empty, returns
-// topmost non-empty parent. returns NULL otherwise
+/**
+ * Destroys a container and all empty parents. Returns the topmost non-empty
+ * parent container, or NULL.
+ */
 swayc_t *destroy_container(swayc_t *container);
-// Destroys view and all empty parent containers. return topmost non-empty
-// parent
+/**
+ * Destroys a view container and all empty parents. Returns the topmost
+ * non-empty parent container, or NULL.
+ */
 swayc_t *destroy_view(swayc_t *view);
 
-// Container Lookup
-
+/**
+ * Finds a container based on test criteria. Returns the first container that
+ * passes the test.
+ */
 swayc_t *swayc_by_test(swayc_t *container, bool (*test)(swayc_t *view, void *data), void *data);
+/**
+ * Finds a parent container with the given swayc_type.
+ */
 swayc_t *swayc_parent_by_type(swayc_t *container, enum swayc_types);
+/**
+ * Finds a parent with the given swayc_layout.
+ */
 swayc_t *swayc_parent_by_layout(swayc_t *container, enum swayc_layouts);
-// Follow focused until type/layout
+/**
+ * Finds the bottom-most focused container of a type.
+ */
 swayc_t *swayc_focus_by_type(swayc_t *container, enum swayc_types);
+/**
+ * Finds the bottom-most focused container of a layout.
+ */
 swayc_t *swayc_focus_by_layout(swayc_t *container, enum swayc_layouts);
 
-
+/**
+ * Gets the swayc_t associated with a wlc_handle.
+ */
 swayc_t *swayc_by_handle(wlc_handle handle);
+/**
+ * Gets the named swayc_t.
+ */
 swayc_t *swayc_by_name(const char *name);
+/**
+ * Gets the active output's container.
+ */
 swayc_t *swayc_active_output(void);
+/**
+ * Gets the active workspace's container.
+ */
 swayc_t *swayc_active_workspace(void);
+/**
+ * Gets the workspace for the given view container.
+ */
 swayc_t *swayc_active_workspace_for(swayc_t *view);
-// set focus to current pointer location and return focused container
+/**
+ * Finds the container currently underneath the pointer.
+ */
 swayc_t *container_under_pointer(void);
 
-// Container information
-
+/**
+ * Returns true if a container is fullscreen.
+ */
 bool swayc_is_fullscreen(swayc_t *view);
+/**
+ * Returns true if this view is focused.
+ */
 bool swayc_is_active(swayc_t *view);
-// Is `parent` the parent of `child`
+/**
+ * Returns true if the parent is an ancestor of the child.
+ */
 bool swayc_is_parent_of(swayc_t *parent, swayc_t *child);
-// Is `child` a child of `parent`
+/**
+ * Returns true if the child is a desecendant of the parent.
+ */
 bool swayc_is_child_of(swayc_t *child, swayc_t *parent);
-// Return gap of specified container
+/**
+ * Returns the gap (padding) of the container.
+ *
+ * This returns the inner gaps for a view, the outer gaps for a workspace, and
+ * 0 otherwise.
+ */
 int swayc_gap(swayc_t *container);
 
-// Mapping functions
-
+/**
+ * Maps a container's children over a function.
+ */
 void container_map(swayc_t *, void (*f)(swayc_t *, void *), void *);
 
-// Mappings
+/**
+ * Set a view as visible or invisible.
+ *
+ * This will perform the required wlc calls as well; it is not sufficient to
+ * simply toggle the boolean in swayc_t.
+ */
 void set_view_visibility(swayc_t *view, void *data);
-// Set or add to gaps
+/**
+ * Set the gaps value for a view.
+ */
 void set_gaps(swayc_t *view, void *amount);
+/**
+ * Add to the gaps value for a view.
+ */
 void add_gaps(swayc_t *view, void *amount);
 
+/**
+ * Issue wlc calls to make the visibility of a container consistent.
+ */
 void update_visibility(swayc_t *container);
 
 #endif