From 4be25abad7d04d29cb0448c9676364f3bb15f984 Mon Sep 17 00:00:00 2001
From: Dave Davenport <qball@gmpclient.org>
Date: Fri, 29 Jul 2016 08:32:34 +0200
Subject: [PATCH] Fix some doxygen warnings.

---
 doc/rofi.doxy.in         |  2 +-
 include/dialogs/run.h    |  6 +++---
 include/dialogs/script.h |  2 +-
 include/dialogs/ssh.h    |  6 +++---
 include/helper.h         |  7 ++-----
 include/history.h        |  2 +-
 include/mode.h           |  5 +++--
 include/scrollbar.h      |  4 +---
 include/settings.h       |  1 -
 include/textbox.h        |  1 +
 include/x11-helper.h     |  6 ++----
 include/xrmoptions.h     |  6 +++---
 source/dialogs/run.c     |  3 ++-
 source/dialogs/ssh.c     |  2 --
 source/x11-helper.c      | 15 +++++++--------
 15 files changed, 30 insertions(+), 38 deletions(-)

diff --git a/doc/rofi.doxy.in b/doc/rofi.doxy.in
index f794564c..9113f5b6 100644
--- a/doc/rofi.doxy.in
+++ b/doc/rofi.doxy.in
@@ -2345,7 +2345,7 @@ PLANTUML_INCLUDE_PATH  =
 # Minimum value: 0, maximum value: 10000, default value: 50.
 # This tag requires that the tag HAVE_DOT is set to YES.
 
-DOT_GRAPH_MAX_NODES    = 15
+DOT_GRAPH_MAX_NODES    = 50
 
 # The MAX_DOT_GRAPH_DEPTH tag can be used to set the maximum depth of the graphs
 # generated by dot. A depth value of 3 means that only nodes reachable from the
diff --git a/include/dialogs/run.h b/include/dialogs/run.h
index c6b5d13d..4a4d9674 100644
--- a/include/dialogs/run.h
+++ b/include/dialogs/run.h
@@ -6,9 +6,9 @@
  * @ingroup MODES
  *
  * This mode uses the following options from the #config object:
- *  * #_Settings::run_command
- *  * #_Settings::run_shell_command
- *  * #_Settings::run_list_command
+ *  * #Settings::run_command
+ *  * #Settings::run_shell_command
+ *  * #Settings::run_list_command
  *
  * @{
  */
diff --git a/include/dialogs/script.h b/include/dialogs/script.h
index 46b9ab6f..37f97d4d 100644
--- a/include/dialogs/script.h
+++ b/include/dialogs/script.h
@@ -11,7 +11,7 @@
  * @param str   The input string to parse
  *
  * Parse an argument string into the right ScriptOptions data object.
- * This is off format: <Name>:<Script>
+ * This is off format: \<Name\>:\<Script\>
  *
  * @returns NULL when it fails, a newly allocated ScriptOptions when successful.
  */
diff --git a/include/dialogs/ssh.h b/include/dialogs/ssh.h
index 55326cb4..d55e2db0 100644
--- a/include/dialogs/ssh.h
+++ b/include/dialogs/ssh.h
@@ -10,9 +10,9 @@
  * It also keeps history of the last choosen hosts.
  *
  * This mode uses the following options from the #config object:
- *  * #_Settings::ssh_command
- *  * #_Settings::parse_known_hosts
- *  * #_Settings::parse_hosts
+ *  * #Settings::ssh_command
+ *  * #Settings::parse_known_hosts
+ *  * #Settings::parse_hosts
  *
  * @{
  */
diff --git a/include/helper.h b/include/helper.h
index e337bf39..42c71297 100644
--- a/include/helper.h
+++ b/include/helper.h
@@ -86,18 +86,15 @@ int find_arg_str ( const char * const key, char** val );
 int find_arg ( const char * const key );
 
 /**
- * @params tokens
  * @param tokens  List of (input) tokens to match.
  * @param input   The entry to match against.
- * @param case_sensitive Whether case is significant.
- * @param index   The current selected index.
- * @param data    User data.
  *
  * Tokenized match, match tokens to line input.
  *
- * @returns 1 when matches, 0 otherwise
+ * @returns TRUE when matches, FALSE otherwise
  */
 int token_match ( GRegex **tokens, const char *input );
+
 /**
  * @param cmd The command to execute.
  *
diff --git a/include/history.h b/include/history.h
index 95a8a048..182cd340 100644
--- a/include/history.h
+++ b/include/history.h
@@ -8,7 +8,7 @@
  * Implements a very simple history module that can be used by a #Mode.
  *
  * This uses the following options from the #config object:
- * * #_Settings::disable_history
+ * * #Settings::disable_history
  *
  * @{
  */
diff --git a/include/mode.h b/include/mode.h
index 4cd2244d..b140ebce 100644
--- a/include/mode.h
+++ b/include/mode.h
@@ -98,8 +98,8 @@ char * mode_get_completion ( const Mode *mode, unsigned int selected_line );
 
 /**
  * @param mode The mode to query
- * @param mretv The menu return value.
- * @param input Pointer to the user input string.
+ * @param menu_retv The menu return value.
+ * @param input Pointer to the user input string. [in][out]
  * @param selected_line the line selected by the user.
  *
  * Acts on the user interaction.
@@ -145,6 +145,7 @@ void *mode_get_private_data ( const Mode *mode );
 
 /**
  * @param mode The mode to query
+ * @param pd   Pointer to private data to attach to the mode.
  *
  * Helper functions for mode.
  * Set the private data object.
diff --git a/include/scrollbar.h b/include/scrollbar.h
index 2c9d732d..d3839fef 100644
--- a/include/scrollbar.h
+++ b/include/scrollbar.h
@@ -21,9 +21,6 @@ typedef struct _scrollbar
 } scrollbar;
 
 /**
- * @param parent the parent window
- * @param vinfo The XVisualInfo to use when creating new window
- * @param map   The colormap to use for new window
  * @param x     The x coordinate (relative to parent) to position the new scrollbar
  * @param y     The y coordinate (relative to parent) to position the new scrollbar
  * @param w     The width of the scrollbar
@@ -68,6 +65,7 @@ void scrollbar_set_max_value ( scrollbar *sb, unsigned int max );
 
 /**
  * @param sb scrollbar object
+ * @param draw the cairo object used to draw itself
  *
  * Draw the scrollbar, used after expose event or update
  */
diff --git a/include/settings.h b/include/settings.h
index d08abd88..b4c915ee 100644
--- a/include/settings.h
+++ b/include/settings.h
@@ -7,7 +7,6 @@
  * \verbatim WL_NORTH_WEST      WL_NORTH      WL_NORTH_EAST \endverbatim
  * \verbatim WL_EAST            WL_CENTER     WL_EAST \endverbatim
  * \verbatim WL_SOUTH_WEST      WL_SOUTH      WL_SOUTH_EAST\endverbatim
- * \endverbatim
  *
  * @ingroup CONFIGURATION
  */
diff --git a/include/textbox.h b/include/textbox.h
index 898f0ac4..3109f577 100644
--- a/include/textbox.h
+++ b/include/textbox.h
@@ -98,6 +98,7 @@ void textbox_text ( textbox *tb, const char *text );
 
 /**
  * @param tb  Handle to the textbox
+ * @param draw The cairo object used to draw itself.
  *
  * Render the textbox.
  */
diff --git a/include/x11-helper.h b/include/x11-helper.h
index f35e20a0..f1b5fb30 100644
--- a/include/x11-helper.h
+++ b/include/x11-helper.h
@@ -13,7 +13,6 @@
  */
 
 /**
- * @param display Connection to the X server.
  * @param w The xcb_window_t to read property from.
  * @param atom The property identifier
  *
@@ -89,13 +88,13 @@ unsigned int x11_get_current_mask ( xkb_stuff *xkb );
  * @param combo String representing the key combo
  * @param mod [out]  The modifier specified (or AnyModifier if not specified)
  * @param key [out]  The key specified
+ * @param release [out] If it should react on key-release, not key-press
  *
  * Parse key from user input string.
  */
 gboolean x11_parse_key ( char *combo, unsigned int *mod, xkb_keysym_t *key, gboolean *release );
 
 /**
- * @param display The connection to the X server.
  * @param box     The window to set the opacity on.
  * @param opacity The opacity value. (0-100)
  *
@@ -128,7 +127,6 @@ typedef struct
 } Color;
 
 /**
- * @param display Connection to the X server.
  * @param name    String representing the color.
  *
  * Allocate a pixel value for an X named color
@@ -144,7 +142,7 @@ void x11_helper_set_cairo_rgba ( cairo_t *d, Color col );
 /**
  * Gets a surface containing the background image of the desktop.
  *
- * @param a cairo surface with the background image of the desktop.
+ * @returns a cairo surface with the background image of the desktop.
  */
 cairo_surface_t * x11_helper_get_bg_surface ( void );
 /*@}*/
diff --git a/include/xrmoptions.h b/include/xrmoptions.h
index ffb916e3..19e89ebc 100644
--- a/include/xrmoptions.h
+++ b/include/xrmoptions.h
@@ -46,7 +46,7 @@ typedef enum
 } XrmOptionType;
 
 /**
- * @param display Handler of the display to fetch the settings from.
+ * @param xcb  Handler object holding connection used to fetch the settings from.
  *
  * Parse the rofi related X resource options of the
  * connected X server.
@@ -73,7 +73,7 @@ void config_parse_cmd_options ( void );
 void config_parse_cmd_options_dynamic ( void );
 
 /**
- * @param display Handler of the display to fetch the settings from.
+ * @param xcb Handler object that holds connection to X11 server to fetch the settings from.
  *
  * Parse the rofi related X resource options of the
  * connected X server.
@@ -114,7 +114,7 @@ void config_parse_xresources_theme_dump ( void );
  * @param type The type of the value
  * @param key  The key refering to this configuration option
  * @param value The value to update based [out][in]
- * @param command Description of this configuration option
+ * @param comment Description of this configuration option
  *
  * Add option (at runtime) to the dynamic option parser.
  */
diff --git a/source/dialogs/run.c b/source/dialogs/run.c
index 523a0b4e..6dd2010f 100644
--- a/source/dialogs/run.c
+++ b/source/dialogs/run.c
@@ -151,12 +151,13 @@ static void delete_entry ( const char *cmd )
 /**
  * @param a The First key to compare
  * @param b The second key to compare
+ * @param data Unused.
  *
  * Function used for sorting.
  *
  * @returns returns less then, equal to and greater than zero is a is less than, is a match or greater than b.
  */
-static int sort_func ( const void *a, const void *b, void *data __attribute__( ( unused ) ) )
+static int sort_func ( const void *a, const void *b, G_GNUC_UNUSED void *data )
 {
     const char *astr = *( const char * const * ) a;
     const char *bstr = *( const char * const * ) b;
diff --git a/source/dialogs/ssh.c b/source/dialogs/ssh.c
index 331e5431..397893dc 100644
--- a/source/dialogs/ssh.c
+++ b/source/dialogs/ssh.c
@@ -473,8 +473,6 @@ static char *_get_display_value ( const Mode *sw, unsigned int selected_line, G_
 /**
  * @param sw Object handle to the SSH Mode object
  * @param tokens The set of tokens to match against
- * @param not_ascii If the entry is pure-ascii
- * @param case_sensitive If the entry should be matched case sensitive
  * @param index The index of the entry to match
  *
  * Match entry against the set of tokens.
diff --git a/source/x11-helper.c b/source/x11-helper.c
index 94762172..13cc8d50 100644
--- a/source/x11-helper.c
+++ b/source/x11-helper.c
@@ -253,12 +253,13 @@ void monitor_dimensions ( int x, int y, workarea *mon )
 }
 
 /**
- * @param x  The x position of the mouse [out]
- * @param y  The y position of the mouse [out]
+ * @param root The X11 window used to find the pointer position. Usually the root window.
+ * @param x    The x position of the mouse [out]
+ * @param y    The y position of the mouse [out]
  *
  * find mouse pointer location
  *
- * @returns 1 when found
+ * @returns TRUE when found, FALSE otherwise
  */
 static int pointer_get ( xcb_window_t root, int *x, int *y )
 {
@@ -270,10 +271,10 @@ static int pointer_get ( xcb_window_t root, int *x, int *y )
         *x = r->root_x;
         *y = r->root_y;
         free ( r );
-        return 1;
+        return TRUE;
     }
 
-    return 0;
+    return FALSE;
 }
 
 // determine which monitor holds the active window, or failing that the mouse pointer
@@ -585,9 +586,7 @@ void x11_set_window_opacity ( xcb_window_t box, unsigned int opacity )
 }
 
 /**
- * @param display The connection to the X server.
- *
- * Fill in the list of Atoms.
+ * Fill in the list of frequently used X11 Atoms.
  */
 static void x11_create_frequently_used_atoms ( void )
 {