core: reformat comments for functions

1 files changed, 92 insertions, 86 deletions

diff --git a/src/core/wee-config.c b/src/core/wee-config.c
index a4fa0e5aa..530bd9d67 100644
--- a/src/core/wee-config.c
+++ b/src/core/wee-config.c
@@ -260,7 +260,7 @@ int config_num_plugin_extensions = 0;
 
 
 /*
- * config_change_sys_rlimit: called when the system resource limits is changed
+ * Callback for changes on option "weechat.startup.sys_rlimit".
  */
 
 void
@@ -275,7 +275,7 @@ config_change_sys_rlimit (void *data, struct t_config_option *option)
 }
 
 /*
- * config_change_save_config_on_exit: called when "save_config_on_exit" flag is changed
+ * Callback for changes on option "weechat.look.save_config_on_exit".
  */
 
 void
@@ -295,7 +295,7 @@ config_change_save_config_on_exit (void *data, struct t_config_option *option)
 }
 
 /*
- * config_change_title: called when title is changed
+ * Callback for changes on option "weechat.look.set_title".
  */
 
 void
@@ -310,7 +310,7 @@ config_change_title (void *data, struct t_config_option *option)
 }
 
 /*
- * config_change_buffers: called when buffers change (for example nicklist)
+ * Callback for changes on options that require a refresh of buffers.
  */
 
 void
@@ -324,7 +324,7 @@ config_change_buffers (void *data, struct t_config_option *option)
 }
 
 /*
- * config_change_buffer_content: called when content of a buffer changes
+ * Callback for changes on options that require a refresh of content of buffer.
  */
 
 void
@@ -339,7 +339,7 @@ config_change_buffer_content (void *data, struct t_config_option *option)
 }
 
 /*
- * config_change_mouse: called when mouse state is changed
+ * Callback for changes on option "weechat.look.mouse".
  */
 
 void
@@ -359,7 +359,7 @@ config_change_mouse (void *data, struct t_config_option *option)
 }
 
 /*
- * config_change_buffer_notify_default: called when buffer default notify changes
+ * Callback for changes on option "weechat.look.buffer_notify_default".
  */
 
 void
@@ -373,7 +373,7 @@ config_change_buffer_notify_default (void *data, struct t_config_option *option)
 }
 
 /*
- * config_change_buffer_time_format: called when buffer time format changes
+ * Callback for changes on option "weechat.look.buffer_time_format".
  */
 
 void
@@ -390,8 +390,7 @@ config_change_buffer_time_format (void *data, struct t_config_option *option)
 }
 
 /*
- * config_compute_prefix_max_length_all_buffers: compute the "prefix_max_length"
- *                                               on all buffers
+ * Computes the "prefix_max_length" on all buffers.
  */
 
 void
@@ -410,7 +409,7 @@ config_compute_prefix_max_length_all_buffers ()
 }
 
 /*
- * config_change_prefix_same_nick: called when "prefix for same nick" changes
+ * Callback for changes on option "weechat.look.prefix_same_nick".
  */
 
 void
@@ -428,7 +427,7 @@ config_change_prefix_same_nick (void *data, struct t_config_option *option)
 }
 
 /*
- * config_change_eat_newline_glitch: called when eat_newline_glitch changes
+ * Callback for changes on option "weechat.look.eat_newline_glitch".
  */
 
 void
@@ -454,7 +453,7 @@ config_change_eat_newline_glitch (void *data, struct t_config_option *option)
 }
 
 /*
- * config_change_highlight_regex: called when highlight_regex changes
+ * Callback for changes on option "weechat.look.highlight_regex".
  */
 
 void
@@ -489,7 +488,7 @@ config_change_highlight_regex (void *data, struct t_config_option *option)
 }
 
 /*
- * config_change_highlight_tags: called when highlight_tags changes
+ * Callback for changes on option "weechat.look.highlight_tags".
  */
 
 void
@@ -515,11 +514,11 @@ config_change_highlight_tags (void *data, struct t_config_option *option)
 }
 
 /*
- * config_change_hotlist: called when hotlist changes
+ * Callback for changes on option "weechat.look.hotlist_sort".
  */
 
 void
-config_change_hotlist (void *data, struct t_config_option *option)
+config_change_hotlist_sort (void *data, struct t_config_option *option)
 {
     /* make C compiler happy */
     (void) data;
@@ -529,7 +528,7 @@ config_change_hotlist (void *data, struct t_config_option *option)
 }
 
 /*
- * config_change_paste_bracketed: called when bracketed paste mode is changed
+ * Callback for changes on option "weechat.look.paste_bracketed".
  */
 
 void
@@ -544,7 +543,7 @@ config_change_paste_bracketed (void *data, struct t_config_option *option)
 }
 
 /*
- * config_change_read_marker: called when read marker is changed
+ * Callback for changes on option "weechat.look.read_marker".
  */
 
 void
@@ -558,7 +557,7 @@ config_change_read_marker (void *data, struct t_config_option *option)
 }
 
 /*
- * config_change_prefix: called when a prefix is changed
+ * Callback for changes on a prefix option.
  */
 
 void
@@ -572,7 +571,7 @@ config_change_prefix (void *data, struct t_config_option *option)
 }
 
 /*
- * config_change_prefix_align_min: called when prefix_align_min is changed
+ * Callback for changes on option "weechat.look.prefix_align_min".
  */
 
 void
@@ -587,8 +586,7 @@ config_change_prefix_align_min (void *data, struct t_config_option *option)
 }
 
 /*
- * config_check_prefix_align_more: check string "prefix align more" (must be
- *                                 max one char wide on screen)
+ * Callback for changes on option "weechat.look.prefix_align_more".
  */
 
 int
@@ -603,8 +601,7 @@ config_check_prefix_align_more (void *data, struct t_config_option *option,
 }
 
 /*
- * config_check_prefix_buffer_align_more: check string "prefix buffer align more"
- *                                        (must be max one char wide on screen)
+ * Callback for changes on option "weechat.look.prefix_buffer_align_more".
  */
 
 int
@@ -620,7 +617,7 @@ config_check_prefix_buffer_align_more (void *data,
 }
 
 /*
- * config_change_color: called when a color is changed by /set command
+ * Callback for changes on a color option.
  */
 
 void
@@ -638,7 +635,7 @@ config_change_color (void *data, struct t_config_option *option)
 }
 
 /*
- * config_change_nick_colors: called when nick colors are changed
+ * Callback for changes on option "weechat.color.chat_nick_colors".
  */
 
 void
@@ -652,7 +649,7 @@ config_change_nick_colors (void *data, struct t_config_option *option)
 }
 
 /*
- * config_change_network_gnutls_ca_file: called when gnutls_ca_file is changed
+ * Callback for changes on option "weechat.network.gnutls_ca_file".
  */
 
 void
@@ -668,7 +665,7 @@ config_change_network_gnutls_ca_file (void *data,
 }
 
 /*
- * config_change_plugin_extension: called when plugin extension is changed
+ * Callback for changes on option "weechat.plugin.extension".
  */
 
 void
@@ -694,8 +691,7 @@ config_change_plugin_extension (void *data, struct t_config_option *option)
 }
 
 /*
- * config_day_change_timer_cb: timer callback for displaying
- *                             "Day changed to xxx" message
+ * Displays message "Day changed to xxx".
  */
 
 int
@@ -752,8 +748,7 @@ config_day_change_timer_cb (void *data, int remaining_calls)
 }
 
 /*
- * config_weechat_init_after_read: initialize some things after reading (or
- *                                 reloading) configuration file
+ * Initializes some things after reading/reloading WeeChat configuration file.
  */
 
 void
@@ -782,7 +777,7 @@ config_weechat_init_after_read ()
         gui_bar_create_default ();
     }
 
-    /* if no key was found config file, then we use default bindings */
+    /* if no key was found configuration file, then we use default bindings */
     for (i = 0; i < GUI_KEY_NUM_CONTEXTS; i++)
     {
         if (!gui_keys[i])
@@ -794,11 +789,12 @@ config_weechat_init_after_read ()
 }
 
 /*
- * config_weechat_reload_cb: reload WeeChat configuration file
- *                           return one of these values:
- *                             WEECHAT_CONFIG_READ_OK
- *                             WEECHAT_CONFIG_READ_MEMORY_ERROR
- *                             WEECHAT_CONFIG_READ_FILE_NOT_FOUND
+ * Reloads WeeChat configuration file.
+ *
+ * Returns:
+ *   WEECHAT_CONFIG_READ_OK: OK
+ *   WEECHAT_CONFIG_READ_MEMORY_ERROR: not enough memory
+ *   WEECHAT_CONFIG_READ_FILE_NOT_FOUND: file not found
  */
 
 int
@@ -840,7 +836,7 @@ config_weechat_reload_cb (void *data, struct t_config_file *config_file)
 }
 
 /*
- * config_weechat_debug_get: get debug level for a plugin (or "core")
+ * Gets debug level for a plugin (or "core").
  */
 
 struct t_config_option *
@@ -852,8 +848,8 @@ config_weechat_debug_get (const char *plugin_name)
 }
 
 /*
- * config_weechat_debug_set_all: set debug for "core" and all plugins, using
- *                               values from [debug] section
+ * Sets debug level for "core" and all plugins, using values from section
+ * "debug".
  */
 
 void
@@ -876,7 +872,7 @@ config_weechat_debug_set_all ()
 }
 
 /*
- * config_weechat_debug_change_cb: called when a debug option is changed
+ * Callback for changes on a debug option.
  */
 
 void
@@ -891,7 +887,7 @@ config_weechat_debug_change_cb (void *data,
 }
 
 /*
- * config_weechat_debug_create_option_cb: create option in "debug" section
+ * Callback called when an option is created in section "debug".
  */
 
 int
@@ -949,7 +945,7 @@ config_weechat_debug_create_option_cb (void *data,
 }
 
 /*
- * config_weechat_debug_delete_option_cb: delete option in "debug" section
+ * Callback called when an option is deleted in section "debug".
  */
 
 int
@@ -971,7 +967,7 @@ config_weechat_debug_delete_option_cb (void *data,
 }
 
 /*
- * config_weechat_debug_set: set debug level for a plugin (or "core")
+ * Sets debug level for a plugin (or "core").
  */
 
 int
@@ -985,7 +981,7 @@ config_weechat_debug_set (const char *plugin_name, const char *value)
 }
 
 /*
- * config_weechat_palette_change_cb: called when a palette option is changed
+ * Callback for changes on a palette option.
  */
 
 void
@@ -1008,7 +1004,7 @@ config_weechat_palette_change_cb (void *data,
 }
 
 /*
- * config_weechat_palette_create_option_cb: create option in "palette" section
+ * Callback called when an option is created in section "palette".
  */
 
 int
@@ -1077,7 +1073,7 @@ config_weechat_palette_create_option_cb (void *data,
 }
 
 /*
- * config_weechat_palette_delete_option_cb: delete option in "palette" section
+ * Callback called when an option is deleted in section "palette".
  */
 
 int
@@ -1105,7 +1101,7 @@ config_weechat_palette_delete_option_cb (void *data,
 }
 
 /*
- * config_weechat_proxy_read_cb: read proxy option in config file
+ * Reads a proxy option in WeeChat configuration file.
  */
 
 int
@@ -1184,7 +1180,7 @@ config_weechat_proxy_read_cb (void *data, struct t_config_file *config_file,
 }
 
 /*
- * config_weechat_bar_read_cb: read bar option in config file
+ * Reads a bar option in WeeChat configuration file.
  */
 
 int
@@ -1263,7 +1259,7 @@ config_weechat_bar_read_cb (void *data, struct t_config_file *config_file,
 }
 
 /*
- * config_weechat_layout_read_cb: read layout option in config file
+ * Reads a layout option in WeeChat configuration file.
  */
 
 int
@@ -1342,7 +1338,7 @@ config_weechat_layout_read_cb (void *data, struct t_config_file *config_file,
 }
 
 /*
- * config_weechat_layout_write: write windows layout in configuration file
+ * Writes layout of windows in WeeChat configuration file.
  */
 
 int
@@ -1379,7 +1375,7 @@ config_weechat_layout_write_tree (struct t_config_file *config_file,
 }
 
 /*
- * config_weechat_layout_write_cb: write layout section in configuration file
+ * Writes section "layout" in WeeChat configuration file.
  */
 
 int
@@ -1415,7 +1411,7 @@ config_weechat_layout_write_cb (void *data, struct t_config_file *config_file,
 }
 
 /*
- * config_weechat_notify_change_cb: callback when notify option is changed
+ * Callback for changes on a notify option.
  */
 
 void
@@ -1429,8 +1425,7 @@ config_weechat_notify_change_cb (void *data, struct t_config_option *option)
 }
 
 /*
- * config_weechat_notify_create_option_cb: callback to create option in "notify"
- *                                         section
+ * Callback called when an option is created in section "notify".
  */
 
 int
@@ -1488,8 +1483,7 @@ config_weechat_notify_create_option_cb (void *data,
 }
 
 /*
- * config_weechat_notify_delete_option_cb: called when a notify option is
- *                                         deleted
+ * Callback called when an option is deleted in section "notify".
  */
 
 int
@@ -1511,10 +1505,14 @@ config_weechat_notify_delete_option_cb (void *data,
 }
 
 /*
- * config_weechat_notify_set: set a notify level for a buffer
- *                            negative value will reset notify for buffer to
- *                            default value (and remove buffer from config file)
- *                            return 1 if ok, 0 if error
+ * Sets a notify level for a buffer.
+ *
+ * A negative value resets notify for buffer to its default value (and
+ * removes buffer from config file).
+ *
+ * Returns:
+ *   1: OK
+ *   0: error
  */
 
 int
@@ -1548,7 +1546,7 @@ config_weechat_notify_set (struct t_gui_buffer *buffer, const char *notify)
 }
 
 /*
- * config_weechat_filter_read_cb: read filter option from config file
+ * Reads a filter option in WeeChat configuration file.
  */
 
 int
@@ -1584,7 +1582,7 @@ config_weechat_filter_read_cb (void *data,
 }
 
 /*
- * config_weechat_filter_write_cb: write filter section in configuration file
+ * Writes a filter option in WeeChat configuration file.
  */
 
 int
@@ -1616,7 +1614,7 @@ config_weechat_filter_write_cb (void *data, struct t_config_file *config_file,
 }
 
 /*
- * config_weechat_key_read_cb: read key option in config file
+ * Reads a key option in WeeChat configuration file.
  */
 
 int
@@ -1658,7 +1656,7 @@ config_weechat_key_read_cb (void *data, struct t_config_file *config_file,
 }
 
 /*
- * config_weechat_key_write_cb: write key section in configuration file
+ * Writes section "key" in WeeChat configuration file.
  */
 
 int
@@ -1703,8 +1701,11 @@ config_weechat_key_write_cb (void *data, struct t_config_file *config_file,
 }
 
 /*
- * config_weechat_init_options: init WeeChat config structure (all core options)
- *                              return: 1 if ok, 0 if error
+ * Creates options in WeeChat configuration.
+ *
+ * Returns:
+ *   1: OK
+ *   0: error
  */
 
 int
@@ -2019,7 +2020,7 @@ config_weechat_init_options ()
            "number_asc, number_desc)"),
         "group_time_asc|group_time_desc|group_number_asc|"
         "group_number_desc|number_asc|number_desc",
-        0, 0, "group_time_asc", NULL, 0, NULL, NULL, &config_change_hotlist, NULL, NULL, NULL);
+        0, 0, "group_time_asc", NULL, 0, NULL, NULL, &config_change_hotlist_sort, NULL, NULL, NULL);
     config_look_hotlist_unique_numbers = config_file_new_option (
         weechat_config_file, ptr_section,
         "hotlist_unique_numbers", "boolean",
@@ -2327,7 +2328,7 @@ config_weechat_init_options ()
         N_("text color for '+' when scrolling bars"),
         NULL, -1, 0, "lightmagenta", NULL, 0,
         NULL, NULL, &config_change_color, NULL, NULL, NULL);
-    /* chat window */
+    /* chat area */
     config_color_chat = config_file_new_option (
         weechat_config_file, ptr_section,
         "chat", "color",
@@ -2548,7 +2549,7 @@ config_weechat_init_options ()
         N_("text color for values"),
         NULL, GUI_COLOR_CHAT_VALUE, 0, "cyan", NULL, 0,
         NULL, NULL, &config_change_color, NULL, NULL, NULL);
-    /* status window */
+    /* status bar */
     config_color_status_number = config_file_new_option (
         weechat_config_file, ptr_section,
         "status_number", "color",
@@ -2635,7 +2636,7 @@ config_weechat_init_options ()
         N_("text color for time (status bar)"),
         NULL, -1, 0, "default", NULL, 0,
         NULL, NULL, &config_change_color, NULL, NULL, NULL);
-    /* input window */
+    /* input bar */
     config_color_input_text_not_found = config_file_new_option (
         weechat_config_file, ptr_section,
         "input_text_not_found", "color",
@@ -2648,7 +2649,7 @@ config_weechat_init_options ()
         N_("text color for actions in input line"),
         NULL, -1, 0, "lightgreen", NULL, 0,
         NULL, NULL, &config_change_color, NULL, NULL, NULL);
-    /* nicklist window */
+    /* nicklist bar */
     config_color_nicklist_group = config_file_new_option (
         weechat_config_file, ptr_section,
         "nicklist_group", "color",
@@ -2952,8 +2953,11 @@ config_weechat_init_options ()
 }
 
 /*
- * config_weechat_init: init WeeChat config structure
- *                      return: 1 if ok, 0 if error
+ * Initializes WeeChat configuration.
+ *
+ * Returns:
+ *   1: OK
+ *   0: error
  */
 
 int
@@ -2995,11 +2999,12 @@ config_weechat_init ()
 }
 
 /*
- * config_weechat_read: read WeeChat configuration file
- *                      return one of these values:
- *                        WEECHAT_CONFIG_READ_OK
- *                        WEECHAT_CONFIG_READ_MEMORY_ERROR
- *                        WEECHAT_CONFIG_READ_FILE_NOT_FOUND
+ * Reads WeeChat configuration file.
+ *
+ * Returns:
+ *   WEECHAT_CONFIG_READ_OK: OK
+ *   WEECHAT_CONFIG_READ_MEMORY_ERROR: not enough memory
+ *   WEECHAT_CONFIG_READ_FILE_NOT_FOUND: file not found
  */
 
 int
@@ -3022,11 +3027,12 @@ config_weechat_read ()
 }
 
 /*
- * config_weechat_write: write WeeChat configuration file
- *                       return one of these values:
- *                         WEECHAT_CONFIG_WRITE_OK
- *                         WEECHAT_CONFIG_WRITE_ERROR
- *                         WEECHAT_CONFIG_WRITE_MEMORY_ERROR
+ * Writes WeeChat configuration file.
+ *
+ * Returns:
+ *   WEECHAT_CONFIG_WRITE_OK: OK
+ *   WEECHAT_CONFIG_WRITE_ERROR: error
+ *   WEECHAT_CONFIG_WRITE_MEMORY_ERROR: not enough memory
  */
 
 int
@@ -3036,7 +3042,7 @@ config_weechat_write ()
 }
 
 /*
- * config_weechat_free: free WeeChat configuration file and vars
+ * Frees WeeChat configuration file and variables.
  */
 
 void