Document more headers.

include/dialogs/combi.h

@@ -5,9 +5,18 @@
  * @defgroup COBIMode Combi
  * @ingroup MODES
  *
+ * Dialog that can combine multiple #Mode into one view.
+ *
+ * This mode uses the following options from the #config object:
+ *  * #Settings::combi_modi
+ *
+ * It creates the following option:
+ *  * Settings::display_combi
+ *
  * @{
  */
 
+/** #Mode object representing the combi dialog. */
 extern Mode combi_mode;
 
 /*@}*/

include/dialogs/dmenu.h

@@ -15,6 +15,9 @@
  */
 int dmenu_switcher_dialog ( void );
 
+/**
+ * Print dmenu mode commandline options to stdout, for use in help menu.
+ */
 void print_dmenu_options ( void );
 
 /*@}*/

include/dialogs/drun.h

@@ -8,6 +8,7 @@
  */
 #include <config.h>
 #ifdef ENABLE_DRUN
+/** #Mode object representing the desktop menu run dialog. */
 extern Mode drun_mode;
 #endif // ENABLE_DRUN
 /*@}*/

include/dialogs/help-keys.h

@@ -10,8 +10,8 @@
  * @{
  */
 /**
- * Internal handle to the help key mode
- */ 
+ * #Mode object representing the help key mode view
+ */
 extern Mode help_keys_mode;
 /*@}*/
 #endif // ROFI_DIALOG_HELPKEYS_H

include/dialogs/run.h

@@ -12,6 +12,7 @@
  *
  * @{
  */
+/** #Mode object representing the run dialog. */
 extern Mode run_mode;
 
 /*@}*/

include/dialogs/ssh.h

@@ -17,9 +17,7 @@
  * @{
  */
 
-/**
- * SSH Mode object.
- */
+/** #Mode object representing the ssh dialog. */
 extern Mode ssh_mode;
 /*@}*/
 #endif // ROFI_DIALOG_SSH_H

include/helper.h

@@ -35,7 +35,7 @@ int helper_parse_setup ( char * string, char ***output, int *length, ... );
 GRegex **tokenize ( const char *input, int case_sensitive );
 
 /**
- * @param tokens Array of regex objects 
+ * @param tokens Array of regex objects
  *
  * Frees the array of regex expressions.
  */
@@ -177,7 +177,7 @@ unsigned int levenshtein ( const char *needle, const char *haystack );
 char * rofi_force_utf8 ( gchar *data, ssize_t length );
 
 /**
- * @param data the array holding latin text 
+ * @param data the array holding latin text
  * @param length the length of the data array
  *
  * Converts latin to UTF-8.

include/rofi.h

@@ -44,13 +44,13 @@ const Mode * rofi_get_mode ( unsigned int index );
  */
 void rofi_set_return_code ( int code );
 /** Reset terminal */
-#define  color_reset        "\033[0m"
+#define  color_reset     "\033[0m"
 /** Set terminal text bold */
-#define  color_bold         "\033[1m"
+#define  color_bold      "\033[1m"
 /** Set terminal text italic */
-#define  color_italic       "\033[2m"
+#define  color_italic    "\033[2m"
 /** Set terminal foreground text green */
-#define color_green         "\033[0;32m"
+#define color_green      "\033[0;32m"
 
 /** Appends instructions on how to report an error. */
 #define ERROR_MSG( a )    a "\n"                                       \

include/view.h

@@ -158,7 +158,7 @@ void rofi_view_hide ( void );
 /**
  * Indicate the current view needs to reload its data.
  * This can only be done when *more* information is available.
- * 
+ *
  * The reloading happens 'lazy', multiple calls might be handled at once.
  */
 void rofi_view_reload ( void  );
@@ -166,7 +166,7 @@ void rofi_view_reload ( void  );
 /**
  * @param state The handle to the view
  * @param mode The new mode to display
- * 
+ *
  * Change the current view to show a different mode.
  */
 void rofi_view_switch_mode ( RofiViewState *state, Mode *mode );
@@ -174,7 +174,7 @@ void rofi_view_switch_mode ( RofiViewState *state, Mode *mode );
 /**
  * @param state The handle to the view
  * @param text An UTF-8 encoded character array with the text to overlay.
- * 
+ *
  * Overlays text over the current view. Passing NULL for text hides the overlay.
  */
 void rofi_view_set_overlay ( RofiViewState *state, const char *text );

include/widgets/textbox.h

@@ -17,6 +17,10 @@
  *
  * @{
  */
+/**
+ * Internal structure of a textbox widget.
+ * @TODO make this internal to textbox
+ */
 typedef struct
 {
     widget          widget;
@@ -37,6 +41,9 @@ typedef struct
     guint           blink_timeout;
 } textbox;
 
+/**
+ * Flags for configuring textbox behaviour and looks during creation.
+ */
 typedef enum
 {
     TB_AUTOHEIGHT = 1 << 0,
@@ -50,25 +57,46 @@ typedef enum
     TB_PASSWORD   = 1 << 22,
     TB_INDICATOR  = 1 << 23,
 } TextboxFlags;
-
+/**
+ * Flags indicating current state of the textbox.
+ */
 typedef enum
 {
-    // Render font normally
+    /** Normal */
     NORMAL     = 0,
+    /** Text in box is urgent. */
     URGENT     = 1,
+    /** Text in box is active. */
     ACTIVE     = 2,
+    /** Text in box is selected. */
     SELECTED   = 4,
+    /** Text in box has pango markup. */
     MARKUP     = 8,
 
-    // Alternating row.
+    /** Text is on an alternate row */
     ALT        = 16,
-    // Render font highlighted (inverted colors.)
+    /** Render font highlighted (inverted colors.) */
     HIGHLIGHT  = 32,
-
+    /** Mask for alternate and highlighted */
     FMOD_MASK  = ( ALT | HIGHLIGHT ),
+    /** Mask of bits indicating state */
     STATE_MASK = ~( SELECTED | MARKUP | ALT | HIGHLIGHT )
 } TextBoxFontType;
 
+/**
+ * @param flags #TextboxFlags indicating the type of textbox.
+ * @param x horizontal positon of textbox
+ * @param y vertical position of textbox
+ * @param w width of textbox
+ * @param h height of textbox
+ * @param tbft #TextBoxFontType current state of textbox.
+ * @param text intial text to display.
+ *
+ * Create a new textbox widget.
+ *
+ * free with #widget_free
+ * @returns a new #textbox
+ */
 textbox* textbox_create ( TextboxFlags flags,
                           short x, short y, short w, short h,
                           TextBoxFontType tbft,
@@ -89,6 +117,14 @@ void textbox_font ( textbox *tb, TextBoxFontType tbft );
  */
 void textbox_text ( textbox *tb, const char *text );
 
+/**
+ * @param tb Handle to the textbox
+ * @param action the #KeyBindingAction to execute on textbox
+ *
+ * Execute an action on the textbox.
+ *
+ * @return TRUE if action was taken.
+ */
 int textbox_keybinding ( textbox *tb, KeyBindingAction action );
 /**
  * @param tb Handle to the textbox
@@ -208,11 +244,44 @@ void textbox_cursor_inc ( textbox *tb );
  */
 void textbox_delete ( textbox *tb, int pos, int dlen );
 
+/**
+ * @param tb Handle to the textbox
+ * @param x The new horizontal position to place with textbox
+ * @param y The new vertical position to place with textbox
+ * @param w The new width of the textbox
+ * @param h The new height of the textbox
+ *
+ * Move and resize the textbox.
+ * @TODO remove for #widget_resize and #widget_move
+ */
 void textbox_moveresize ( textbox *tb, int x, int y, int w, int h );
+/**
+ * Get the (estimated) with of a character, can be used to calculate window width.
+ *
+ * @returns the estimated width of a character.
+ */
 int textbox_get_estimated_char_height ( void );
+/**
+ * @param p The new default PangoContext
+ *
+ * Set the default pango context (with font description) for all textboxes.
+ */
 void textbox_set_pango_context ( PangoContext *p );
+/**
+ * @param tb Handle to the textbox
+ * @param list New pango attributes
+ *
+ * Sets #list as active pango attributes.
+ */
 void textbox_set_pango_attributes ( textbox *tb, PangoAttrList *list );
 
+/**
+ * @param tb Handle to the textbox
+ *
+ * Get the list of currently active pango attributes.
+ *
+ * @returns the pango attributes
+ */
 PangoAttrList *textbox_get_pango_attributes ( textbox *tb );
 
 /**

include/widgets/widget.h

@@ -141,7 +141,6 @@ gboolean widget_need_redraw ( widget *wid );
  */
 gboolean widget_clicked ( widget *wid, xcb_button_press_event_t *xbe );
 
-
 /**
  * @param wid The widget handle
  * @param cb The widget click callback

include/x11-helper.h

@@ -23,15 +23,22 @@
  */
 char* window_get_text_prop ( xcb_window_t w, xcb_atom_t atom );
 
+/**
+ * @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 );
 
-/**
- * xcb_window_t info.
- */
+/** 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 );
 
 /**
- * Release keyboard.
+ * @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 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 );
 
 /**

include/xrmoptions.h

@@ -36,7 +36,7 @@
  */
 
 /**
- *  Type of the config options. 
+ *  Type of the config options.
  */
 typedef enum
 {

source/helper.c

@@ -537,12 +537,8 @@ int config_sanity_check ( void )
 
     // Check size
     {
-        int      ssize = monitor_get_smallest_size ( );
         workarea mon;
-        if ( monitor_active ( &mon ) ) {
-            ssize = MIN ( mon.w, mon.h );
-        }
-        else{
+        if ( !monitor_active ( &mon ) ) {
             const char *name = config.monitor;
             if ( name && name[0] == '-' ) {
                 int index = name[1] - '0';

source/widgets/widget.c

@@ -113,7 +113,7 @@ void widget_queue_redraw ( widget *wid )
         // Find toplevel widget.
         while ( iter->parent != NULL ) {
             iter->need_redraw = TRUE;
-            iter = iter->parent;
+            iter              = iter->parent;
         }
         iter->need_redraw = TRUE;
     }

source/x11-helper.c

@@ -71,7 +71,6 @@ xcb_stuff           *xcb = &xcb_int;
 xcb_depth_t         *depth       = NULL;
 xcb_visualtype_t    *visual      = NULL;
 xcb_colormap_t      map          = XCB_COLORMAP_NONE;
-xcb_depth_t         *root_depth  = NULL;
 xcb_visualtype_t    *root_visual = NULL;
 xcb_atom_t          netatoms[NUM_NETATOMS];
 const char          *netatom_names[] = { EWMH_ATOMS ( ATOM_CHAR ) };
@@ -325,17 +324,7 @@ void x11_dump_monitor_layout ( void )
     }
 }
 
-int monitor_get_smallest_size ( void )
-{
-    int size = MIN ( xcb->screen->width_in_pixels, xcb->screen->height_in_pixels );
-    for ( workarea *iter = xcb->monitors; iter; iter = iter->next ) {
-        size = MIN ( iter->w, size );
-        size = MIN ( iter->h, size );
-    }
-
-    return size;
-}
-int monitor_get_dimension ( int monitor_id, workarea *mon )
+static int monitor_get_dimension ( int monitor_id, workarea *mon )
 {
     memset ( mon, 0, sizeof ( workarea ) );
     mon->w = xcb->screen->width_in_pixels;
@@ -351,7 +340,7 @@ int monitor_get_dimension ( int monitor_id, workarea *mon )
     return FALSE;
 }
 // find the dimensions of the monitor displaying point x,y
-void monitor_dimensions ( int x, int y, workarea *mon )
+static void monitor_dimensions ( int x, int y, workarea *mon )
 {
     memset ( mon, 0, sizeof ( workarea ) );
     mon->w = xcb->screen->width_in_pixels;
@@ -415,7 +404,7 @@ static int monitor_active_from_id ( int mon_id, workarea *mon )
             if ( xcb_ewmh_get_desktop_viewport_reply ( &xcb->ewmh, c, &vp, NULL ) ) {
                 if ( current_desktop < vp.desktop_viewport_len ) {
                     monitor_dimensions ( vp.desktop_viewport[current_desktop].x,
-                            vp.desktop_viewport[current_desktop].y, mon );
+                                         vp.desktop_viewport[current_desktop].y, mon );
                     xcb_ewmh_get_desktop_viewport_reply_wipe ( &vp );
                     return TRUE;
                 }
@@ -467,7 +456,7 @@ static int monitor_active_from_id ( int mon_id, workarea *mon )
         // This is our give up point.
         return FALSE;
     }
-    g_log ( LOG_DOMAIN, G_LOG_LEVEL_DEBUG, "Failed to find monitor, fall back to monitor showing mouse.");
+    g_log ( LOG_DOMAIN, G_LOG_LEVEL_DEBUG, "Failed to find monitor, fall back to monitor showing mouse." );
     return monitor_active_from_id ( -5, mon );
 }
 
@@ -766,6 +755,7 @@ void x11_setup ( xkb_stuff *xkb )
 
 void x11_create_visual_and_colormap ( void )
 {
+    xcb_depth_t          *root_depth = NULL;
     xcb_depth_iterator_t depth_iter;
     for ( depth_iter = xcb_screen_allowed_depths_iterator ( xcb->screen ); depth_iter.rem; xcb_depth_next ( &depth_iter ) ) {
         xcb_depth_t               *d = depth_iter.data;