Document more headers.

1 files changed, 128 insertions, 18 deletions

diff --git a/include/x11-helper.h b/include/x11-helper.h
index aa3f6095..e07b2eb5 100644
--- a/include/x11-helper.h
+++ b/include/x11-helper.h
@@ -23,15 +23,22 @@
  */
 char* window_get_text_prop ( xcb_window_t w, xcb_atom_t atom );
 
-void window_set_atom_prop ( xcb_window_t w, xcb_atom_t prop, xcb_atom_t *atoms, int count );
-
 /**
- * xcb_window_t info.
+ * @param w The xcb_window_t to set property on
+ * @param prop Atom of the property to change
+ * @param atoms List of atoms to change the property too
+ * @param count The length of the #atoms list.
+ *
+ * Set property on window.
  */
+void window_set_atom_prop ( xcb_window_t w, xcb_atom_t prop, xcb_atom_t *atoms, int count );
+
+/** For getting the atoms in an enum  */
 #define ATOM_ENUM( x )    x
+/** Get the atoms as strings. */
 #define ATOM_CHAR( x )    # x
 
-// usable space on a monitor
+/** Atoms we want to pre-load */
 #define EWMH_ATOMS( X )           \
     X ( _NET_WM_WINDOW_OPACITY ), \
     X ( I3_SOCKET_PATH ),         \
@@ -42,53 +49,93 @@ void window_set_atom_prop ( xcb_window_t w, xcb_atom_t prop, xcb_atom_t *atoms,
     X ( _MOTIF_WM_HINTS ),        \
     X ( ESETROOT_PMAP_ID )
 
+/** enumeration of the atoms. */
 enum { EWMH_ATOMS ( ATOM_ENUM ), NUM_NETATOMS };
-
+/** atoms as string */
 extern const char *netatom_names[];
+/** atoms */
 extern xcb_atom_t netatoms[NUM_NETATOMS];
 
+/**
+ * Enumerator describing the different modifier keys.
+ */
 enum
 {
+    /** Shift key */
     X11MOD_SHIFT,
+    /** Control Key */
     X11MOD_CONTROL,
+    /** Alt key */
     X11MOD_ALT,
+    /** Meta key */
     X11MOD_META,
+    /** Super (window) key */
     X11MOD_SUPER,
+    /** Hyper key */
     X11MOD_HYPER,
+    /** Any modifier */
     X11MOD_ANY,
+    /** Number of modifier keys */
     NUM_X11MOD
 };
 
+/**
+ * Structure describing a workarea/monitor.
+ */
 typedef struct _workarea
 {
+    /** numeric monitor id. */
     int              monitor_id;
+    /** if monitor is set as primary monitor. */
     int              primary;
-    int              x, y, w, h;
+    /** Horizontal location (in pixels) of the monitor. */
+    int              x;
+    /** Vertical location  (in pixels) of the monitor. */
+    int              y;
+    /** Width of the monitor. */
+    int              w;
+    /** Height of the monitor */
+    int              h;
+    /** Output name of the monitor, e.g. eDP1 or VGA-1 */
     char             *name;
+    /** Pointer to next monitor */
     struct _workarea *next;
 } workarea;
-int monitor_active ( workarea *mon );
 
-// find the dimensions of the monitor displaying point x,y
-void monitor_dimensions ( int x, int y, workarea *mon );
-// Find the dimensions of the monitor specified by user.
-int monitor_get_dimension ( int monitor_id, workarea *mon );
-int monitor_get_smallest_size ( void );
+/**
+ * @param mon workarea to be filled in.
+ *
+ * Fills in #mon with the information about the monitor rofi should show on.
+ *
+ * @returns TRUE if monitor is found, FALSE if no monitor could be detected.
+ */
+int monitor_active ( workarea *mon );
 
 /**
- * Release keyboard.
+ * Release keyboard grab on root window.
  */
 void release_keyboard ( void );
+/**
+ * Release pointer grab on root window.
+ */
 void release_pointer ( void );
 
 /**
  * @param w       xcb_window_t we want to grab keyboard on.
  *
- * Grab keyboard and mouse.
+ * Grab keyboard.
  *
  * @return 1 when keyboard is grabbed, 0 not.
  */
 int take_keyboard ( xcb_window_t w );
+
+/**
+ * @param w       xcb_window_t we want to grab mouse on.
+ *
+ * Grab mouse.
+ *
+ * @return 1 when mouse is grabbed, 0 not.
+ */
 int take_pointer ( xcb_window_t w );
 
 /**
@@ -98,6 +145,13 @@ int take_pointer ( xcb_window_t w );
  */
 unsigned int x11_canonalize_mask ( unsigned int mask );
 
+/**
+ * @param xkb the xkb structure.
+ *
+ * Calculates the mask of all active modifier keys.
+ *
+ * @returns the mask describing all active modifier keys.
+ */
 unsigned int x11_get_current_mask ( xkb_stuff *xkb );
 
 /**
@@ -126,10 +180,21 @@ void x11_set_window_opacity ( xcb_window_t box, unsigned int opacity );
  */
 void x11_setup ( xkb_stuff *xkb );
 
-extern xcb_depth_t      *depth;
+/**
+ * Depth of visual
+ */
+extern xcb_depth_t *depth;
+/**
+ * Visual to use for creating window
+ */
 extern xcb_visualtype_t *visual;
-extern xcb_colormap_t   map;
-extern xcb_depth_t      *root_depth;
+/**
+ * Color map to use for creating window
+ */
+extern xcb_colormap_t map;
+/**
+ * Depth of root window.
+ */
 extern xcb_visualtype_t *root_visual;
 /**
  * This function tries to create a 32bit TrueColor colormap.
@@ -137,9 +202,19 @@ extern xcb_visualtype_t *root_visual;
  */
 void x11_create_visual_and_colormap ( void );
 
+/**
+ * Structure describing a cairo color.
+ */
 typedef struct
 {
-    double red, green, blue, alpha;
+    /** red channel */
+    double red;
+    /** green channel */
+    double green;
+    /** blue channel */
+    double blue;
+    /**  alpha channel */
+    double alpha;
 } Color;
 
 /**
@@ -149,10 +224,32 @@ typedef struct
  */
 Color color_get ( const char *const name );
 
+/**
+ * @param d cairo drawing context to set color on
+ *
+ * Set cairo drawing context source color to the background color.
+ */
 void color_background ( cairo_t *d );
+
+/**
+ * @param d cairo drawing context to set color on
+ *
+ * Set cairo drawing context source color to the border color.
+ */
 void color_border ( cairo_t *d  );
+/**
+ * @param d cairo drawing context to set color on
+ *
+ * Set cairo drawing context source color to the separator color.
+ */
 void color_separator ( cairo_t *d );
 
+/**
+ * @param d cairo drawing context to set color on.
+ * @param col The color to set.
+ *
+ * Sets col as cairo source color.
+ */
 void x11_helper_set_cairo_rgba ( cairo_t *d, Color col );
 
 /**
@@ -167,7 +264,20 @@ cairo_surface_t * x11_helper_get_bg_surface ( void );
  * Used for positioning rofi.
  */
 void x11_build_monitor_layout ( void );
+
+/**
+ * Dump the monitor layout to stdout.
+ */
 void x11_dump_monitor_layout ( void );
+
+/**
+ * @param mask the mask to check for key
+ * @param key the key to check in mask
+ *
+ * Check if key is in the modifier mask.
+ *
+ * @returns TRUE if key is in the modifier mask
+ */
 int x11_modifier_active ( unsigned int mask, int key );
 
 /**