Add more documentation to functions/header files

src/con.c

@@ -24,7 +24,12 @@ char *colors[] = {
     "#aa00aa"
 };
 
-
+/*
+ * Create a new container (and attach it to the given parent, if not NULL).
+ * This function initializes the data structures and creates the appropriate
+ * X11 IDs using x_con_init().
+ *
+ */
 Con *con_new(Con *parent) {
     Con *new = scalloc(sizeof(Con));
     TAILQ_INSERT_TAIL(&all_cons, new, all_cons);
@@ -56,6 +61,12 @@ Con *con_new(Con *parent) {
     return new;
 }
 
+/*
+ * Attaches the given container to the given parent. This happens when moving
+ * a container or when inserting a new container at a specific place in the
+ * tree.
+ *
+ */
 void con_attach(Con *con, Con *parent) {
     con->parent = parent;
     Con *current = TAILQ_FIRST(&(parent->focus_head));
@@ -72,6 +83,10 @@ void con_attach(Con *con, Con *parent) {
     TAILQ_INSERT_TAIL(&(parent->focus_head), con, focused);
 }
 
+/*
+ * Detaches the given container from its current parent
+ *
+ */
 void con_detach(Con *con) {
     if (con->type == CT_FLOATING_CON) {
         TAILQ_REMOVE(&(con->parent->floating_head), con, floating_windows);
@@ -222,6 +237,11 @@ bool con_is_floating(Con *con) {
     return (con->floating >= FLOATING_AUTO_ON);
 }
 
+/*
+ * Returns the container with the given client window ID or NULL if no such
+ * container exists.
+ *
+ */
 Con *con_by_window_id(xcb_window_t window) {
     Con *con;
     TAILQ_FOREACH(con, &all_cons, all_cons)
@@ -230,6 +250,11 @@ Con *con_by_window_id(xcb_window_t window) {
     return NULL;
 }
 
+/*
+ * Returns the container with the given frame ID or NULL if no such container
+ * exists.
+ *
+ */
 Con *con_by_frame_id(xcb_window_t frame) {
     Con *con;
     TAILQ_FOREACH(con, &all_cons, all_cons)
@@ -286,6 +311,11 @@ void con_fix_percent(Con *con, int action) {
     }
 }
 
+/*
+ * Toggles fullscreen mode for the given container. Fullscreen mode will not be
+ * entered when there already is a fullscreen container on this workspace.
+ *
+ */
 void con_toggle_fullscreen(Con *con) {
     Con *workspace, *fullscreen;
     LOG("toggling fullscreen for %p / %s\n", con, con->name);
@@ -324,6 +354,8 @@ void con_toggle_fullscreen(Con *con) {
 }
 
 /*
+ * Moves the given container to the currently focused container on the given
+ * workspace.
  * TODO: is there a better place for this function?
  *
  */

src/match.c

@@ -4,10 +4,21 @@
  * i3 - an improved dynamic tiling window manager
  * © 2009-2010 Michael Stapelberg and contributors (see also: LICENSE)
  *
+ * A "match" is a data structure which acts like a mask or expression to match
+ * certain windows or not. For example, when using commands, you can specify a
+ * command like this: [title="*Firefox*"] kill. The title member of the match
+ * data structure will then be filled and i3 will check each window using
+ * match_matches_window() to find the windows affected by this command.
+ *
  */
 
 #include "all.h"
 
+/*
+ * Check if a match is empty. This is necessary while parsing commands to see
+ * whether the user specified a match at all.
+ *
+ */
 bool match_is_empty(Match *match) {
     /* we cannot simply use memcmp() because the structure is part of a
      * TAILQ and I don’t want to start with things like assuming that the
@@ -22,6 +33,10 @@ bool match_is_empty(Match *match) {
             match->floating == M_ANY);
 }
 
+/*
+ * Check if a match data structure matches the given window.
+ *
+ */
 bool match_matches_window(Match *match, i3Window *window) {
     /* TODO: pcre, full matching, … */
     if (match->class != NULL && window->class_class != NULL && strcasecmp(match->class, window->class_class) == 0) {

src/tree.c

@@ -10,7 +10,7 @@ struct Con *focused;
 struct all_cons_head all_cons = TAILQ_HEAD_INITIALIZER(all_cons);
 
 /*
- * Loads tree from ~/.i3/_restart.json
+ * Loads tree from ~/.i3/_restart.json (used for in-place restarts).
  *
  */
 bool tree_restore() {
@@ -201,6 +201,10 @@ void tree_close(Con *con, bool kill_window) {
     con_focus(next);
 }
 
+/*
+ * Closes the current container using tree_close().
+ *
+ */
 void tree_close_con() {
     assert(focused != NULL);
     if (focused->type == CT_WORKSPACE) {
@@ -248,6 +252,10 @@ void tree_split(Con *con, orientation_t orientation) {
     con_attach(con, new);
 }
 
+/*
+ * Moves focus one level up.
+ *
+ */
 void level_up() {
     /* We can focus up to the workspace, but not any higher in the tree */
     if (focused->parent->type != CT_CON &&
@@ -258,6 +266,10 @@ void level_up() {
     con_focus(focused->parent);
 }
 
+/*
+ * Moves focus one level down.
+ *
+ */
 void level_down() {
     /* Go down the focus stack of the current node */
     Con *next = TAILQ_FIRST(&(focused->focus_head));
@@ -276,6 +288,11 @@ static void mark_unmapped(Con *con) {
         mark_unmapped(current);
 }
 
+/*
+ * Renders the tree, that is rendering all outputs using render_con() and
+ * pushing the changes to X11 using x_push_changes().
+ *
+ */
 void tree_render() {
     if (croot == NULL)
         return;
@@ -296,6 +313,11 @@ void tree_render() {
     printf("-- END RENDERING --\n");
 }
 
+/*
+ * Changes focus in the given way (next/previous) and given orientation
+ * (horizontal/vertical).
+ *
+ */
 void tree_next(char way, orientation_t orientation) {
     /* 1: get the first parent with the same orientation */
     Con *parent = focused->parent;
@@ -333,6 +355,11 @@ void tree_next(char way, orientation_t orientation) {
     con_focus(next);
 }
 
+/*
+ * Moves the current container in the given way (next/previous) and given
+ * orientation (horizontal/vertical).
+ *
+ */
 void tree_move(char way, orientation_t orientation) {
     /* 1: get the first parent with the same orientation */
     Con *parent = focused->parent;

src/x.c

@@ -105,6 +105,10 @@ void x_reinit(Con *con) {
     memset(&(state->window_rect), 0, sizeof(Rect));
 }
 
+/*
+ * Kills the window decoration associated with the given container.
+ *
+ */
 void x_con_kill(Con *con) {
     con_state *state;
 
@@ -137,6 +141,10 @@ static bool window_supports_protocol(xcb_window_t window, xcb_atom_t atom) {
     return result;
 }
 
+/*
+ * Kills the given X11 window using WM_DELETE_WINDOW (if supported).
+ *
+ */
 void x_window_kill(xcb_window_t window) {
     /* if this window does not support WM_DELETE_WINDOW, we kill it the hard way */
     if (!window_supports_protocol(window, atoms[WM_DELETE_WINDOW])) {
@@ -161,6 +169,10 @@ void x_window_kill(xcb_window_t window) {
     xcb_flush(conn);
 }
 
+/*
+ * Draws the decoration of the given container onto its parent.
+ *
+ */
 void x_draw_decoration(Con *con) {
     Con *parent;