Add more documentation to functions/header files

include/con.h

@@ -1,24 +1,116 @@
 #ifndef _CON_H
 #define _CON_H
 
+/**
+ * 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);
+
+/**
+ * Sets input focus to the given container. Will be updated in X11 in the next
+ * run of x_push_changes().
+ *
+ */
 void con_focus(Con *con);
+
+/**
+ * Returns true when this node is a leaf node (has no children)
+ *
+ */
 bool con_is_leaf(Con *con);
+
+/**
+ * Returns true if this node accepts a window (if the node swallows windows,
+ * it might already have swallowed enough and cannot hold any more).
+ *
+ */
 bool con_accepts_window(Con *con);
+
+/**
+ * Gets the output container (first container with CT_OUTPUT in hierarchy) this
+ * node is on.
+ *
+ */
 Con *con_get_output(Con *con);
+
+/**
+ * Gets the workspace container this node is on.
+ *
+ */
 Con *con_get_workspace(Con *con);
+
+/**
+ * Returns the first fullscreen node below this node.
+ *
+ */
 Con *con_get_fullscreen_con(Con *con);
+
+/**
+ * Returns true if the node is floating.
+ *
+ */
 bool con_is_floating(Con *con);
+
+/**
+ * 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);
+
+/**
+ * Returns the container with the given frame ID or NULL if no such container
+ * exists.
+ *
+ */
 Con *con_by_frame_id(xcb_window_t frame);
+
+/**
+ * Returns the first container which wants to swallow this window
+ * TODO: priority
+ *
+ */
 Con *con_for_window(i3Window *window, Match **store_match);
+
+/**
+ * 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);
+
+/**
+ * Detaches the given container from its current parent
+ *
+ */
 void con_detach(Con *con);
 
-enum { WINDOW_ADD = 0, WINDOW_REMOVE = 1 };
+/**
+ * Updates the percent attribute of the children of the given container. This
+ * function needs to be called when a window is added or removed from a
+ * container.
+ *
+ */
 void con_fix_percent(Con *con, int action);
+enum { WINDOW_ADD = 0, WINDOW_REMOVE = 1 };
+
+/**
+ * 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);
 
+/**
+ * Moves the given container to the currently focused container on the given
+ * workspace.
+ * TODO: is there a better place for this function?
+ *
+ */
 void con_move_to_workspace(Con *con, Con *workspace);
 
 #endif

include/match.h

@@ -1,7 +1,17 @@
 #ifndef _MATCH_H
 #define _MATCH_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);
+
+/**
+ * Check if a match data structure matches the given window.
+ *
+ */
 bool match_matches_window(Match *match, i3Window *window);
 
 #endif

include/render.h

@@ -5,6 +5,14 @@
 #ifndef _RENDER_H
 #define _RENDER_H
 
+/**
+ * "Renders" the given container (and its children), meaning that all rects are
+ * updated correctly. Note that this function does not call any xcb_*
+ * functions, so the changes are completely done in memory only (and
+ * side-effect free). As soon as you call x_push_changes(), the changes will be
+ * updated in X11.
+ *
+ */
 void render_con(Con *con);
 
 #endif

include/tree.h

@@ -12,16 +12,76 @@ extern Con *focused;
 TAILQ_HEAD(all_cons_head, Con);
 extern struct all_cons_head all_cons;
 
+/**
+ * Initializes the tree by creating the root node, adding all RandR outputs
+ * to the tree (that means randr_init() has to be called before) and
+ * assigning a workspace to each RandR output.
+ *
+ */
 void tree_init();
+
+/**
+ * Opens an empty container in the current container
+ *
+ */
 Con *tree_open_con(Con *con);
+
+/**
+ * Splits (horizontally or vertically) the given container by creating a new
+ * container which contains the old one and the future ones.
+ *
+ */
 void tree_split(Con *con, orientation_t orientation);
+
+/**
+ * Moves focus one level up.
+ *
+ */
 void level_up();
+
+/**
+ * Moves focus one level down.
+ *
+ */
 void level_down();
+
+/**
+ * Renders the tree, that is rendering all outputs using render_con() and
+ * pushing the changes to X11 using x_push_changes().
+ *
+ */
 void tree_render();
+
+/**
+ * Closes the current container using tree_close().
+ *
+ */
 void tree_close_con();
+
+/**
+ * Changes focus in the given way (next/previous) and given orientation
+ * (horizontal/vertical).
+ *
+ */
 void tree_next(char way, orientation_t orientation);
+
+/**
+ * Moves the current container in the given way (next/previous) and given
+ * orientation (horizontal/vertical).
+ *
+ */
 void tree_move(char way, orientation_t orientation);
+
+/**
+ * Closes the given container including all children
+ *
+ */
 void tree_close(Con *con, bool kill_window);
+
+/**
+ * Loads tree from ~/.i3/_restart.json (used for in-place restarts).
+ *
+ */
 bool tree_restore();
 
 #endif

include/window.h

@@ -1,8 +1,27 @@
 #ifndef _WINDOW_H
 #define _WINDOW_H
 
+/**
+ * Updates the WM_CLASS (consisting of the class and instance) for the
+ * given window.
+ *
+ */
 void window_update_class(i3Window *win, xcb_get_property_reply_t *prop);
+
+/**
+ * Updates the name by using _NET_WM_NAME (encoded in UTF-8) for the given
+ * window. Further updates using window_update_name_legacy will be ignored.
+ *
+ */
 void window_update_name(i3Window *win, xcb_get_property_reply_t *prop);
+
+/**
+ * Updates the name by using WM_NAME (encoded in COMPOUND_TEXT). We do not
+ * touch what the client sends us but pass it to xcb_image_text_8. To get
+ * proper unicode rendering, the application has to use _NET_WM_NAME (see
+ * window_update_name()).
+ *
+ */
 void window_update_name_legacy(i3Window *win, xcb_get_property_reply_t *prop);
 
 #endif

include/x.h

@@ -5,12 +5,51 @@
 #ifndef _X_H
 #define _X_H
 
+/**
+ * Initializes the X11 part for the given container. Called exactly once for
+ * every container from con_new().
+ *
+ */
 void x_con_init(Con *con);
+
+/**
+ * Re-initializes the associated X window state for this container. You have
+ * to call this when you assign a client to an empty container to ensure that
+ * its state gets updated correctly.
+ *
+ */
 void x_reinit(Con *con);
+
+/**
+ * Kills the window decoration associated with the given container.
+ *
+ */
 void x_con_kill(Con *con);
+
+/**
+ * Kills the given X11 window using WM_DELETE_WINDOW (if supported).
+ *
+ */
 void x_window_kill(xcb_window_t window);
+
+/**
+ * Draws the decoration of the given container onto its parent.
+ *
+ */
 void x_draw_decoration(Con *con);
+
+/**
+ * Pushes all changes (state of each node, see x_push_node() and the window
+ * stack) to X11.
+ *
+ */
 void x_push_changes(Con *con);
+
+/**
+ * Raises the specified container in the internal stack of X windows. The
+ * next call to x_push_changes() will make the change visible in X11.
+ *
+ */
 void x_raise_con(Con *con);
 
 #endif

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;