Add more documentation.

Current state: 61% coverage.

doc/rofi.doxy.in

@@ -1859,7 +1859,7 @@ MAN_LINKS              = NO
 # captures the structure of the code including all documentation.
 # The default value is: NO.
 
-GENERATE_XML           = NO
+GENERATE_XML           = YES
 
 # The XML_OUTPUT tag is used to specify where the XML pages will be put. If a
 # relative path is entered the value of OUTPUT_DIRECTORY will be put in front of

include/dialogs/help-keys.h

@@ -4,8 +4,14 @@
 /**
  * @defgroup HELPKEYSMode KeysHelp
  * @ingroup MODES
+ *
+ * Displays the different keybindings available in *rofi*
+ *
  * @{
  */
+/**
+ * Internal handle to the help key mode
+ */ 
 extern Mode help_keys_mode;
 /*@}*/
 #endif // ROFI_DIALOG_HELPKEYS_H

include/helper.h

@@ -30,9 +30,15 @@ int helper_parse_setup ( char * string, char ***output, int *length, ... );
  *
  * Tokenize the string on spaces.
  *
- * @returns a newly allocated 2 dimensional array of strings.
+ * @returns a newly allocated array of regex objest
  */
 GRegex **tokenize ( const char *input, int case_sensitive );
+
+/**
+ * @param tokens Array of regex objects 
+ *
+ * Frees the array of regex expressions.
+ */
 void tokenize_free ( GRegex ** tokens );
 
 /**
@@ -149,13 +155,46 @@ void cmd_set_arguments ( int argc, char **argv );
  * @returns path
  */
 char *rofi_expand_path ( const char *input );
+
+/**
+ * @param needle The string to find match weight off
+ * @param haystack The string to match against
+ *
+ * UTF-8 aware levenshtein distance calculation
+ *
+ * @returns the levenshtein distance between needle and haystack
+ */
 unsigned int levenshtein ( const char *needle, const char *haystack );
 
 /**
+ * @param data the unvalidated character array holding possible UTF-8 data
+ * @param length the length of the data array
+ *
  * Convert string to valid utf-8, replacing invalid parts with replacement character.
+ *
+ * @returns the converted UTF-8 string
  */
 char * rofi_force_utf8 ( gchar *data, ssize_t length );
+
+/**
+ * @param data the array holding latin text 
+ * @param length the length of the data array
+ *
+ * Converts latin to UTF-8.
+ *
+ * @return the UTF-8 representation of data
+ */
 char * rofi_latin_to_utf8_strdup ( const char *input, gssize length );
+
+/**
+ * @param tokens Array of regexes used for matching
+ * @param input The input string to find the matches on
+ * @param retv The Attribute list to update with matches
+ *
+ * Creates a set of pango attributes highlighting the matches found in the input string.
+ *
+ * @returns the updated retv list.
+ */
 PangoAttrList *token_match_get_pango_attr ( GRegex **tokens, const char *input, PangoAttrList *retv );
 /*@}*/
 #endif // ROFI_HELPER_H

include/keyb.h

@@ -7,6 +7,9 @@
  * @{
  */
 
+/**
+ * List of all possible actions that can be triggered by a keybinding.
+ */
 typedef enum
 {
     /** Paste from primary clipboard */
@@ -105,6 +108,9 @@ void cleanup_abe ( void );
  */
 KeyBindingAction abe_find_action ( unsigned int mask, xkb_keysym_t key );
 
+/**
+ * Trigger keybinding on key release.
+ */
 void abe_trigger_release ( void );
 
 /*@}*/

include/rofi.h

@@ -36,6 +36,12 @@ unsigned int rofi_get_num_enabled_modi ( void );
  */
 const Mode * rofi_get_mode ( unsigned int index );
 
+/**
+ * @param code the code to return
+ *
+ * Return value are used for integrating dmenu rofi in scripts.
+ * This function sets the code that rofi will return on exit.
+ */
 void rofi_set_return_code ( int code );
 /** Reset terminal */
 #define  color_reset        "\033[0m"
@@ -46,6 +52,7 @@ void rofi_set_return_code ( int code );
 /** Set terminal foreground text green */
 #define color_green         "\033[0;32m"
 
+/** Appends instructions on how to report an error. */
 #define ERROR_MSG( a )    a "\n"                                       \
     "If you suspect this is caused by a bug in rofi,\n"                \
     "please report the following information to rofi's github page:\n" \
@@ -54,6 +61,7 @@ void rofi_set_return_code ( int code );
     " * Steps to reproduce\n"                                          \
     " * The version of rofi you are running\n\n"                       \
     " <i>https://github.com/DaveDavenport/rofi/</i>"
+/** Indicates if ERROR_MSG uses pango markup */
 #define ERROR_MSG_MARKUP    TRUE
 /*@}*/
 #endif

include/view-internal.h

@@ -17,63 +17,84 @@
 
 struct RofiViewState
 {
+    /** #Mode bound to to this view. */
     Mode             *sw;
 
-    // Update/Refilter list.
+    /** Flag indicating if view needs to be refiltered. */
     int              refilter;
-    int              rchanged;
 
+    /** Main #box widget holding different elements. */
     box              *main_box;
-    // Entries
+    /** #box widget packing the input bar widgets. */
     box              *input_bar;
+    /** #textbox showing the prompt in the input bar. */
+    textbox          *prompt;
+    /** #textbox with the user input in the input bar. */
+    textbox          *text;
+    /** #textbox showing the state of the case sensitive and sortng. */
+    textbox          *case_indicator;
+    /** #separator widget below the input bar. */
     separator        *input_bar_separator;
 
-    textbox          *prompt;
+    /** #listview holding the displayed elements. */
-    textbox          *text;
-    textbox          *case_indicator;
-
     listview         *list_view;
-    // Small overlay.
+    /** #textbox widget showing the overlay. */
     textbox          *overlay;
+    /** Array with the levenshtein distance for each eleemnt. */
     int              *distance;
+    /** Array with the translation between the filtered and unfiltered list. */
     unsigned int     *line_map;
-
+    /** number of (unfiltered) elements to show. */
     unsigned int     num_lines;
 
-    // Selected element.
+    /** number of (filtered) elements to show. */
     unsigned int     filtered_lines;
-    // Last offset in paginating.
-    unsigned int     last_offset;
 
+    /** Previously called key action. */
     KeyBindingAction prev_action;
+    /** Time previous key action was executed. */
     xcb_timestamp_t  last_button_press;
 
+    /** Indicate view should terminate */
     int              quit;
+    /** Indicate if we should absorb the key release */
     int              skip_absorb;
-    // Return state
+    /** The selected line (in the unfiltered list) */
     unsigned int     selected_line;
+    /** The return state of the view */
     MenuReturn       retv;
+    /** Calculated border width */
     unsigned int     border;
+    /** Monitor #workarea the view is displayed on */
     workarea         mon;
 
-    // Sidebar view
+    /** #box holding the different modi buttons */
     box              *sidebar_bar;
+    /** number of modi to display */
     unsigned int     num_modi;
+    /** Array of #textbox that act as buttons for switching modi */
     textbox          **modi;
-
+    /** Settings of the menu */
     MenuFlags        menu_flags;
+    /** If mouse was within view previously */
     int              mouse_seen;
-
+    /** Flag indicating if view needs to be reloaded. */
     int              reload;
-    // Handlers.
+    /** X11 event loop to be called for this view. */
     void             ( *x11_event_loop )( struct RofiViewState *state, xcb_generic_event_t *ev, xkb_stuff *xkb );
+    /** The funciton to be called when finalizing this view */
     void             ( *finalize )( struct RofiViewState *state );
 
+    /** Width of the view */
     int              width;
+    /** Height of the view */
     int              height;
+    /** X position of the view */
     int              x;
+    /** Y position of the view */
     int              y;
 
+    /** Regexs used for matching */
     GRegex           **tokens;
 };
 /** @} */

include/view.h

@@ -141,8 +141,53 @@ void rofi_view_queue_redraw ( void );
  */
 void rofi_view_cleanup ( void );
 
+/**
+ * @param state The handle to the view
+ *
+ * Get the mode currently displayed by the view.
+ *
+ * @returns the mode currently displayed by the view
+ */
 Mode * rofi_view_get_mode ( RofiViewState *state );
+
+/**
+ * Unmap the current view.
+ */
+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  );
+
+/**
+ * @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 );
+
+/**
+ * @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 );
+
+/**
+ * @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.
+ */
+void __create_window ( MenuFlags menu_flags );
 /** @} */
+
 /***
  * @defgroup ViewThreadPool ViewThreadPool
  * @ingroup View
@@ -152,16 +197,14 @@ Mode * rofi_view_get_mode ( RofiViewState *state );
  *
  * @{
  */
+/**
+ * Initialize the threadpool
+ */
 void rofi_view_workers_initialize ( void );
+/**
+ * Stop all threads and free the resources used by the threadpool
+ */
 void rofi_view_workers_finalize ( void );
 
-void __create_window ( MenuFlags menu_flags );
-void rofi_view_set_overlay ( RofiViewState *state, const char *text );
-/**
- * Unmap the window.
- */
-void rofi_view_hide ( void );
-void rofi_view_reload ( void  );
-void rofi_view_switch_mode ( RofiViewState *state, Mode *mode );
 /**@}*/
 #endif

include/widgets/box.h

@@ -14,6 +14,10 @@
  *
  * @{
  */
+
+/**
+ * Abstract handle to the box widget internal state.
+ */
 typedef struct _box   box;
 
 /**

include/widgets/separator.h

@@ -11,6 +11,10 @@
  *
  * @{
  */
+
+/**
+ * Abstract handle to the separator widget internal state.
+ */
 typedef struct _separator   separator;
 
 /**

include/widgets/widget.h

@@ -15,6 +15,11 @@
  *
  * @{
  */
+
+/**
+ * Abstract structure holding internal state of a widget.
+ * Structure is elaborated in widget-internal.h
+ */
 typedef struct _widget   widget;
 
 /**

include/xrmoptions.h

@@ -35,13 +35,20 @@
  * @{
  */
 
-// This maps xresource options to config structure.
+/**
+ *  Type of the config options. 
+ */
 typedef enum
 {
+    /** Config option is string */
     xrm_String  = 0,
+    /** Config option is an unsigned number */
     xrm_Number  = 1,
+    /** Config option is a signed number */
     xrm_SNumber = 2,
+    /** Config option is a boolean (true/false) value*/
     xrm_Boolean = 3,
+    /** Config option is a character */
     xrm_Char    = 4
 } XrmOptionType;
 
@@ -136,6 +143,13 @@ void print_options ( void );
  */
 void print_help_msg ( const char *option, const char *type, const char*text, const char *def, int isatty );
 
+/**
+ * @param length the length of the returned array
+ *
+ * Creates an array with a strings describing each keybinding.
+ *
+ * @returns an array of string with length elements
+ */
 char ** config_parser_return_display_help ( unsigned int *length );
 
 /* @}*/

source/view.c

@@ -946,7 +946,6 @@ static void rofi_view_refilter ( RofiViewState *state )
         }
     }
     state->refilter = FALSE;
-    state->rchanged = TRUE;
     TICK_N ( "Filter done" );
 }
 /**
@@ -1350,7 +1349,6 @@ RofiViewState *rofi_view_create ( Mode *sw,
     state->skip_absorb   = FALSE;
     //We want to filter on the first run.
     state->refilter       = TRUE;
-    state->rchanged       = TRUE;
     state->border         = config.padding + config.menu_bw;
     state->x11_event_loop = rofi_view_mainloop_iter;
     state->finalize       = finalize;