Update code documentation

doc/rofi.doxy.in

@@ -838,7 +838,7 @@ EXCLUDE_SYMBOLS        =
 # that contain example code fragments that are included (see the \include
 # command).
 
-EXAMPLE_PATH           = ../example/
+#EXAMPLE_PATH           = ../example/
 
 # If the value of the EXAMPLE_PATH tag contains directories, you can use the
 # EXAMPLE_PATTERNS tag to specify one or more wildcard pattern (like *.cpp and

include/helper.h

@@ -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 input the char array holding latin text
  * @param length the length of the data array
  *
  * Converts latin to UTF-8.

include/mode-private.h

@@ -2,7 +2,7 @@
 #define ROFI_MODE_PRIVATE_H
 
 /**
- * @param data The #self pointer.
+ * @param data Pointer to #Mode object.
  *
  * Mode free function.
  */

include/mode.h

@@ -175,7 +175,7 @@ void mode_set_config ( Mode *mode );
 
 /**
  * @param mode The mode to query
- * @param intput The input to process
+ * @param input The input to process
  *
  * This processes the input so it can be used for matching and sorting.
  * This includes removing pango markup.

include/view.h

@@ -33,7 +33,6 @@ typedef enum
 /**
  * @param sw the Mode to show.
  * @param input A pointer to a string where the inputted data is placed.
- * @param prompt The prompt to show.
  * @param message Extra message to display.
  * @param flags   Flags indicating state of the menu.
  * @param finalize the finailze callback
@@ -42,9 +41,7 @@ typedef enum
  *
  * @returns The command issued (see MenuReturn)
  */
-RofiViewState *rofi_view_create ( Mode *sw, const char *input, const char *message, MenuFlags flags, void ( *finalize )(
-                                      RofiViewState * ) )
-__attribute__ ( ( nonnull ( 1, 2, 5 ) ) );
+RofiViewState *rofi_view_create ( Mode *sw, const char *input, const char *message, MenuFlags flags, void ( *finalize )( RofiViewState * ) ) __attribute__ ( ( nonnull ( 1, 2, 5 ) ) );
 
 /**
  * @param state The Menu Handle
@@ -53,10 +50,41 @@ __attribute__ ( ( nonnull ( 1, 2, 5 ) ) );
  */
 void rofi_view_finalize ( RofiViewState *state );
 
+/**
+ * @param state the Menu handle
+ *
+ * Get the return value associated to the users action.
+ *
+ * @returns the return value
+ */
 MenuReturn rofi_view_get_return_value ( const RofiViewState *state );
+/**
+ * @param state the Menu handle
+ *
+ * Returns the index of the next visible position.
+ *
+ * @return the next position.
+ */
 unsigned int rofi_view_get_next_position ( const RofiViewState *state );
+/**
+ * @param state the Menu handle
+ * @param event the event to handle
+ * @param xkb  the keyboard handle
+ *
+ * Process an Xevent.
+ */
 void rofi_view_itterrate ( RofiViewState *state, xcb_generic_event_t *event, xkb_stuff *xkb );
+/**
+ * @param state the Menu handle
+ *
+ * @returns returns if this state is completed.
+ */
 unsigned int rofi_view_get_completed ( const RofiViewState *state );
+/**
+ * @param state the Menu handle
+ *
+ * @returns the raw user input.
+ */
 const char * rofi_view_get_user_input ( const RofiViewState *state );
 
 /**
@@ -90,6 +118,12 @@ void rofi_view_restart ( RofiViewState *state );
  */
 void rofi_view_update ( RofiViewState *state );
 
+/**
+ * @param state The handle to the view
+ * @param action The keyboard action
+ *
+ * @returns TRUE if action was handled.
+ */
 gboolean rofi_view_trigger_action ( RofiViewState *state, KeyBindingAction action );
 
 /**
@@ -185,7 +219,7 @@ void rofi_view_set_overlay ( RofiViewState *state, const char *text );
  * @param menu_flags The state of the new window.
  *
  * Creates the internal 'Cached' window that gets reused between views.
- * @TODO: Internal call to view exposed.
+ * TODO: Internal call to view exposed.
  */
 void __create_window ( MenuFlags menu_flags );
 /** @} */

include/widgets/listview.h

@@ -99,7 +99,7 @@ void listview_nav_up ( listview *lv );
  */
 void listview_nav_down ( listview *lv );
 /**
- * @param state The listview handle
+ * @param lv The listview handle
  *
  * Move the selection one column to the right.
  * - No wrap around.
@@ -107,14 +107,14 @@ void listview_nav_down ( listview *lv );
  */
 void listview_nav_right ( listview *lv );
 /**
- * @param state The listview handle
+ * @param lv The listview handle 
  *
  * Move the selection one column to the left.
  * - No wrap around.
  */
 void listview_nav_left ( listview *lv );
 /**
- * @param state The listview handle
+ * @param lv The listview handle 
  *
  * Move the selection one page down.
  * - No wrap around.
@@ -123,7 +123,7 @@ void listview_nav_left ( listview *lv );
 void listview_nav_page_next ( listview *lv );
 
 /**
- * @param state The current RofiViewState
+ * @param lv The listview handle 
  *
  * Move the selection one page up.
  * - No wrap around.
@@ -202,7 +202,7 @@ void listview_set_scroll_type ( listview *lv, ScrollType type );
 void listview_set_mouse_activated_cb ( listview *lv, listview_mouse_activated_cb cb, void *udata );
 /**
  * @param lv Handler to the listview object
- * @param enabled
+ * @param enable boolean to enable/disable multi-select
  *
  * Enable,disable multi-select.
  */

include/widgets/textbox.h

@@ -19,7 +19,7 @@
  */
 /**
  * Internal structure of a textbox widget.
- * @TODO make this internal to textbox
+ * TODO make this internal to textbox
  */
 typedef struct
 {
@@ -217,7 +217,7 @@ void textbox_delete ( textbox *tb, int pos, int dlen );
  * @param h The new height of the textbox
  *
  * Move and resize the textbox.
- * @TODO remove for #widget_resize and #widget_move
+ * TODO remove for #widget_resize and #widget_move
  */
 void textbox_moveresize ( textbox *tb, int x, int y, int w, int h );
 /**
@@ -236,7 +236,7 @@ void textbox_set_pango_context ( PangoContext *p );
  * @param tb Handle to the textbox
  * @param list New pango attributes
  *
- * Sets #list as active pango attributes.
+ * Sets list as active pango attributes.
  */
 void textbox_set_pango_attributes ( textbox *tb, PangoAttrList *list );
 

include/widgets/widget-internal.h

@@ -40,7 +40,7 @@ struct _widget
 
     /** widget clicked callback */
     widget_clicked_cb clicked;
-    /** user data for ::clicked callback */
+    /** user data for clicked callback */
     void              *clicked_cb_data;
 
     /** Free widget callback */

include/widgets/widget.h

@@ -71,15 +71,15 @@ void widget_disable ( widget *widget );
 void widget_enable ( widget *widget );
 
 /**
- * @param tb  Handle to the widget
- * @param draw The cairo object used to draw itself.
+ * @param widget tb  Handle to the widget
+ * @param d The cairo object used to draw itself.
  *
  * Render the textbox.
  */
 void widget_draw ( widget *widget, cairo_t *d );
 
 /**
- * @param tb  Handle to the widget
+ * @param widget Handle to the widget
  *
  * Free the widget and all allocated memory.
  */
@@ -137,7 +137,7 @@ void widget_update ( widget *widget );
  */
 void widget_queue_redraw ( widget *widget );
 /**
- * @param widget The widget handle
+ * @param wid The widget handle
  *
  * Check the flag indicating the widget needs to be redrawn.
  */
@@ -166,10 +166,10 @@ void widget_set_clicked_handler ( widget *wid, widget_clicked_cb cb, void *udata
 
 /**
  * @param wid The widget handle
- * @param xmd The motion notify object.
+ * @param xme The motion notify object.
  *
  * Motion notify.
- * @TODO make this like clicked with callback.
+ * TODO make this like clicked with callback.
  * returns TRUE when handled.
  */
 gboolean widget_motion_notify ( widget *wid, xcb_motion_notify_event_t *xme );

include/x11-helper.h

@@ -27,7 +27,7 @@ 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.
+ * @param count The length of the atoms list.
  *
  * Set property on window.
  */

source/helper.c

@@ -56,7 +56,9 @@ const char *const monitor_position_entries[] = {
     "on monitor with focused window",
     "on monitor that has mouse pointer"
 };
-static int        stored_argc   = 0;
+/** copy of the argc for use in commandline argument parser. */
+static int        stored_argc = 0;
+/** copy of the argv pointer for use in the commandline argument parser */
 static char       **stored_argv = NULL;
 
 void cmd_set_arguments ( int argc, char **argv )
@@ -188,35 +190,40 @@ static gchar *fuzzy_to_regex ( const char * input )
     g_string_free ( str, FALSE );
     return retv;
 }
+
+// Macro for quickly generating regex for matching.
+static inline GRegex * R ( const char *s, int case_sensitive  )
+{
+    return g_regex_new ( s, G_REGEX_OPTIMIZE | ( ( case_sensitive ) ? 0 : G_REGEX_CASELESS ), 0, NULL );
+}
+
 static GRegex * create_regex ( const char *input, int case_sensitive )
 {
-// Macro for quickly generating regex for matching.
-#define R( s )    g_regex_new ( s, G_REGEX_OPTIMIZE | ( ( case_sensitive ) ? 0 : G_REGEX_CASELESS ), 0, NULL )
     GRegex * retv = NULL;
     gchar  *r;
     switch ( config.matching_method )
     {
     case MM_GLOB:
         r    = glob_to_regex ( input );
-        retv = R ( r );
+        retv = R ( r, case_sensitive );
         g_free ( r );
         break;
     case MM_REGEX:
-        retv = R ( input );
+        retv = R ( input, case_sensitive );
         if ( retv == NULL ) {
             r    = g_regex_escape_string ( input, -1 );
-            retv = R ( r );
+            retv = R ( r, case_sensitive );
             g_free ( r );
         }
         break;
     case MM_FUZZY:
         r    = fuzzy_to_regex ( input );
-        retv = R ( r );
+        retv = R ( r, case_sensitive );
         g_free ( r );
         break;
     default:
         r    = g_regex_escape_string ( input, -1 );
-        retv = R ( r );
+        retv = R ( r, case_sensitive );
         g_free ( r );
         break;
     }
@@ -595,6 +602,7 @@ char *rofi_expand_path ( const char *input )
     return retv;
 }
 
+/** Return the minimum value of a,b,c */
 #define MIN3( a, b, c )    ( ( a ) < ( b ) ? ( ( a ) < ( c ) ? ( a ) : ( c ) ) : ( ( b ) < ( c ) ? ( b ) : ( c ) ) )
 
 unsigned int levenshtein ( const char *needle, const char *haystack )

source/view.c

@@ -438,7 +438,9 @@ static RofiViewState * __rofi_view_state_create ( void )
 {
     return g_malloc0 ( sizeof ( RofiViewState ) );
 }
-
+/**
+ * Structure with data to process by each worker thread.
+ */
 typedef struct _thread_state
 {
     RofiViewState *state;