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