core: add missing comments before functions when the result must be freed after use

20 files changed, 62 insertions, 27 deletions

diff --git a/src/core/wee-config-file.c b/src/core/wee-config-file.c
index d204b5755..473efb640 100644
--- a/src/core/wee-config-file.c
+++ b/src/core/wee-config-file.c
@@ -398,6 +398,8 @@ config_file_search_section (struct t_config_file *config_file,
 
 /*
  * Builds full name for an option, using format: "file.section.option".
+ *
+ * Note: result must be freed after use.
  */
 
 char *
diff --git a/src/core/wee-eval.c b/src/core/wee-eval.c
index ecc2abd27..b16225661 100644
--- a/src/core/wee-eval.c
+++ b/src/core/wee-eval.c
@@ -239,6 +239,8 @@ end:
  *                        or hdata[ptr].var1.var2)
  *
  * See /help in WeeChat for examples.
+ *
+ * Note: result must be freed after use.
  */
 
 char *
diff --git a/src/core/wee-hook.c b/src/core/wee-hook.c
index 7a47b951f..12426ef5e 100644
--- a/src/core/wee-hook.c
+++ b/src/core/wee-hook.c
@@ -2722,6 +2722,8 @@ hook_modifier (struct t_weechat_plugin *plugin, const char *modifier,
 
 /*
  * Executes a modifier hook.
+ *
+ * Note: result must be freed after use.
  */
 
 char *
diff --git a/src/core/wee-secure.c b/src/core/wee-secure.c
index 226fe6e0b..cc8da3346 100644
--- a/src/core/wee-secure.c
+++ b/src/core/wee-secure.c
@@ -611,6 +611,8 @@ secure_get_passphrase_from_user (const char *error)
  *
  * Returns passphrase read in file (only the first line with max length of
  * 1024 chars), or NULL if error.
+ *
+ * Note: result must be freed after use.
  */
 
 char *
diff --git a/src/core/wee-string.c b/src/core/wee-string.c
index 35e5a7ec5..58ae2cb5c 100644
--- a/src/core/wee-string.c
+++ b/src/core/wee-string.c
@@ -68,6 +68,8 @@ struct t_hashtable *string_hashtable_shared = NULL;
 /*
  * Defines a "strndup" function for systems where this function does not exist
  * (FreeBSD and maybe others).
+ *
+ * Note: result must be freed after use.
  */
 
 char *
@@ -1797,7 +1799,7 @@ string_split_shared (const char *string, const char *separators, int keep_eol,
  *   Posix compliance, split(), string arguments, and
  *   iterator interface by Gustavo Niemeyer, April 2003.
  *
- * Note: result must be freed with string_free_split.
+ * Note: result must be freed after use with function string_free_split().
  */
 
 char **
@@ -2059,7 +2061,8 @@ string_build_with_split_string (const char **split_string,
  * Splits a list of commands separated by 'separator' and escaped with '\'.
  * Empty commands are removed, spaces on the left of each commands are stripped.
  *
- * Note: result must be freed with free_multi_command.
+ * Note: result must be freed after use with function
+ * string_free_split_command().
  */
 
 char **
diff --git a/src/gui/curses/gui-curses-chat.c b/src/gui/curses/gui-curses-chat.c
index a662d4b24..4731058fc 100644
--- a/src/gui/curses/gui-curses-chat.c
+++ b/src/gui/curses/gui-curses-chat.c
@@ -1879,6 +1879,8 @@ gui_chat_draw_free_buffer (struct t_gui_window *window, int clear_chat)
 
 /*
  * Gets line content in bare display.
+ *
+ * Note: result must be freed after use.
  */
 
 char *
diff --git a/src/gui/gui-bar-item.c b/src/gui/gui-bar-item.c
index 1b668e159..d3eea0512 100644
--- a/src/gui/gui-bar-item.c
+++ b/src/gui/gui-bar-item.c
@@ -365,6 +365,8 @@ gui_bar_item_get_vars (const char *item_name,
  * For example:  if item == "[time]"
  *               returns: color(delimiter) + "[" +
  *                        (value of item "time") + color(delimiter) + "]"
+ *
+ * Note: result must be freed after use.
  */
 
 char *
diff --git a/src/gui/gui-bar-window.c b/src/gui/gui-bar-window.c
index 546c5aedc..842de339c 100644
--- a/src/gui/gui-bar-window.c
+++ b/src/gui/gui-bar-window.c
@@ -667,8 +667,10 @@ gui_bar_window_content_get (struct t_gui_bar_window *bar_window,
 }
 
 /*
- * Gets content of a bar window, formatted for display, according to filling for
- * bar position.
+ * Gets content of a bar window, formatted for display, according to filling
+ * for bar position.
+ *
+ * Note: result must be freed after use.
  */
 
 char *
diff --git a/src/gui/gui-chat.c b/src/gui/gui-chat.c
index 48e2e236c..ff607d937 100644
--- a/src/gui/gui-chat.c
+++ b/src/gui/gui-chat.c
@@ -548,6 +548,8 @@ gui_chat_change_time_format ()
 
 /*
  * Builds a string with prefix and message.
+ *
+ * Note: result must be freed after use.
  */
 
 char *
@@ -590,6 +592,8 @@ gui_chat_build_string_prefix_message (struct t_gui_line *line)
 
 /*
  * Builds a string with message and tags.
+ *
+ * Note: result must be freed after use.
  */
 
 
diff --git a/src/plugins/alias/alias.c b/src/plugins/alias/alias.c
index 82c92cadd..c0df3a3d7 100644
--- a/src/plugins/alias/alias.c
+++ b/src/plugins/alias/alias.c
@@ -177,6 +177,8 @@ alias_string_add_arguments (char **alias, int *length, char **argv, int start,
  *   $n-m arguments from n to m
  *   $*   all arguments
  *   $~   last argument
+ *
+ * Note: result must be freed after use.
  */
 
 char *
diff --git a/src/plugins/aspell/weechat-aspell.c b/src/plugins/aspell/weechat-aspell.c
index 463409df7..4c35dff95 100644
--- a/src/plugins/aspell/weechat-aspell.c
+++ b/src/plugins/aspell/weechat-aspell.c
@@ -497,7 +497,7 @@ weechat_aspell_check_word (struct t_aspell_speller_buffer *speller_buffer,
  *
  * Returns a string with format: "suggest1,suggest2,suggest3".
  *
- * Note: result (if not NULL) must be freed after use.
+ * Note: result must be freed after use (if not NULL).
  */
 
 char *
diff --git a/src/plugins/irc/irc-ctcp.c b/src/plugins/irc/irc-ctcp.c
index 6abab06eb..0009d4b3d 100644
--- a/src/plugins/irc/irc-ctcp.c
+++ b/src/plugins/irc/irc-ctcp.c
@@ -319,6 +319,8 @@ irc_ctcp_reply_to_nick (struct t_irc_server *server,
 
 /*
  * Replaces variables in CTCP format.
+ *
+ * Note: result must be freed after use.
  */
 
 char *
@@ -497,6 +499,8 @@ irc_ctcp_replace_variables (struct t_irc_server *server, const char *format)
 
 /*
  * Returns filename for DCC, without double quotes.
+ *
+ * Note: result must be freed after use.
  */
 
 char *
diff --git a/src/plugins/irc/irc-message.c b/src/plugins/irc/irc-message.c
index 01ffcc17f..855ac045e 100644
--- a/src/plugins/irc/irc-message.c
+++ b/src/plugins/irc/irc-message.c
@@ -349,6 +349,8 @@ irc_message_parse_to_hashtable (struct t_irc_server *server,
 
 /*
  * Encodes/decodes an IRC message using a charset.
+ *
+ * Note: result must be freed after use.
  */
 
 char *
diff --git a/src/plugins/irc/irc-nick.c b/src/plugins/irc/irc-nick.c
index b9df84bf9..0877f331a 100644
--- a/src/plugins/irc/irc-nick.c
+++ b/src/plugins/irc/irc-nick.c
@@ -95,6 +95,8 @@ irc_nick_is_nick (const char *string)
 /*
  * Duplicates a nick and stops at first char in list (using option
  * irc.look.nick_color_stop_chars).
+ *
+ * Note: result must be freed after use.
  */
 
 char *
diff --git a/src/plugins/logger/logger-tail.c b/src/plugins/logger/logger-tail.c
index fe2d62053..6355c1d25 100644
--- a/src/plugins/logger/logger-tail.c
+++ b/src/plugins/logger/logger-tail.c
@@ -58,7 +58,7 @@ logger_tail_last_eol (const char *string_start, const char *string_ptr)
 /*
  * Returns last lines of a file.
  *
- * Note: result must be freed with function "logger_tail_free".
+ * Note: result must be freed after use with function logger_tail_free().
  */
 
 struct t_logger_line *
diff --git a/src/plugins/logger/logger.c b/src/plugins/logger/logger.c
index 887d792b1..06e0ff4ca 100644
--- a/src/plugins/logger/logger.c
+++ b/src/plugins/logger/logger.c
@@ -65,7 +65,7 @@ struct t_hook *logger_timer = NULL;    /* timer to flush log files          */
  *   - "~": user home
  *   - date/time specifiers (see man strftime)
  *
- * Note: returned value must freed after use.
+ * Note: result must be freed after use.
  */
 
 char *
@@ -141,7 +141,7 @@ logger_create_directory ()
 /*
  * Builds full name of buffer.
  *
- * Note: value must be freed after use.
+ * Note: result must be freed after use.
  */
 
 char *
@@ -390,6 +390,8 @@ end:
 
 /*
  * Builds log filename for a buffer.
+ *
+ * Note: result must be freed after use.
  */
 
 char *
diff --git a/src/plugins/plugin-api.c b/src/plugins/plugin-api.c
index e1cd8e693..157a94d04 100644
--- a/src/plugins/plugin-api.c
+++ b/src/plugins/plugin-api.c
@@ -741,7 +741,7 @@ plugin_api_info_color_rgb2term_cb (void *data, const char *info_name,
 /*
  * Returns WeeChat infolist "bar".
  *
- * Note: result must be freed with function "weechat_infolist_free".
+ * Note: result must be freed after use with function weechat_infolist_free().
  */
 
 struct t_infolist *
@@ -797,7 +797,7 @@ plugin_api_infolist_bar_cb (void *data, const char *infolist_name,
 /*
  * Returns WeeChat infolist "bar_item".
  *
- * Note: result must be freed with function "weechat_infolist_free".
+ * Note: result must be freed after use with function weechat_infolist_free().
  */
 
 struct t_infolist *
@@ -854,7 +854,7 @@ plugin_api_infolist_bar_item_cb (void *data, const char *infolist_name,
 /*
  * Returns WeeChat infolist "bar_window".
  *
- * Note: result must be freed with function "weechat_infolist_free".
+ * Note: result must be freed after use with function weechat_infolist_free().
  */
 
 struct t_infolist *
@@ -926,7 +926,7 @@ plugin_api_infolist_bar_window_cb (void *data, const char *infolist_name,
 /*
  * Returns WeeChat infolist "buffer".
  *
- * Note: result must be freed with function "weechat_infolist_free".
+ * Note: result must be freed after use with function weechat_infolist_free().
  */
 
 struct t_infolist *
@@ -983,7 +983,7 @@ plugin_api_infolist_buffer_cb (void *data, const char *infolist_name,
 /*
  * Returns WeeChat infolist "buffer_lines".
  *
- * Note: result must be freed with function "weechat_infolist_free".
+ * Note: result must be freed after use with function weechat_infolist_free().
  */
 
 struct t_infolist *
@@ -1028,7 +1028,7 @@ plugin_api_infolist_buffer_lines_cb (void *data, const char *infolist_name,
 /*
  * Returns WeeChat infolist "filter".
  *
- * Note: result must be freed with function "weechat_infolist_free".
+ * Note: result must be freed after use with function weechat_infolist_free().
  */
 
 struct t_infolist *
@@ -1066,7 +1066,7 @@ plugin_api_infolist_filter_cb (void *data, const char *infolist_name,
 /*
  * Returns WeeChat infolist "history".
  *
- * Note: result must be freed with function "weechat_infolist_free".
+ * Note: result must be freed after use with function weechat_infolist_free().
  */
 
 struct t_infolist *
@@ -1105,7 +1105,7 @@ plugin_api_infolist_history_cb (void *data, const char *infolist_name,
 /*
  * Returns WeeChat infolist "hook".
  *
- * Note: result must be freed with function "weechat_infolist_free".
+ * Note: result must be freed after use with function weechat_infolist_free().
  */
 
 struct t_infolist *
@@ -1137,7 +1137,7 @@ plugin_api_infolist_hook_cb (void *data, const char *infolist_name,
 /*
  * Returns WeeChat infolist "hotlist".
  *
- * Note: result must be freed with function "weechat_infolist_free".
+ * Note: result must be freed after use with function weechat_infolist_free().
  */
 
 struct t_infolist *
@@ -1172,7 +1172,7 @@ plugin_api_infolist_hotlist_cb (void *data, const char *infolist_name,
 /*
  * Returns WeeChat infolist "key".
  *
- * Note: result must be freed with function "weechat_infolist_free".
+ * Note: result must be freed after use with function weechat_infolist_free().
  */
 
 struct t_infolist *
@@ -1214,7 +1214,7 @@ plugin_api_infolist_key_cb (void *data, const char *infolist_name,
 /*
  * Returns WeeChat infolist "layout".
  *
- * Note: result must be freed with function "weechat_infolist_free".
+ * Note: result must be freed after use with function weechat_infolist_free().
  */
 
 struct t_infolist *
@@ -1249,7 +1249,7 @@ plugin_api_infolist_layout_cb (void *data, const char *infolist_name,
 /*
  * Returns WeeChat infolist "nicklist".
  *
- * Note: result must be freed with function "weechat_infolist_free".
+ * Note: result must be freed after use with function weechat_infolist_free().
  */
 
 struct t_infolist *
@@ -1281,7 +1281,7 @@ plugin_api_infolist_nicklist_cb (void *data, const char *infolist_name,
 /*
  * Returns WeeChat infolist "option".
  *
- * Note: result must be freed with function "weechat_infolist_free".
+ * Note: result must be freed after use with function weechat_infolist_free().
  */
 
 struct t_infolist *
@@ -1310,7 +1310,7 @@ plugin_api_infolist_option_cb (void *data, const char *infolist_name,
 /*
  * Returns WeeChat infolist "plugin".
  *
- * Note: result must be freed with function "weechat_infolist_free".
+ * Note: result must be freed after use with function weechat_infolist_free().
  */
 
 struct t_infolist *
@@ -1367,7 +1367,7 @@ plugin_api_infolist_plugin_cb (void *data, const char *infolist_name,
 /*
  * Returns WeeChat infolist "proxy".
  *
- * Note: result must be freed with function "weechat_infolist_free".
+ * Note: result must be freed after use with function weechat_infolist_free().
  */
 
 struct t_infolist *
@@ -1424,7 +1424,7 @@ plugin_api_infolist_proxy_cb (void *data, const char *infolist_name,
 /*
  * Returns WeeChat infolist "url_options".
  *
- * Note: result must be freed with function "weechat_infolist_free".
+ * Note: result must be freed after use with function weechat_infolist_free().
  */
 
 struct t_infolist *
@@ -1458,7 +1458,7 @@ plugin_api_infolist_url_options_cb (void *data, const char *infolist_name,
 /*
  * Returns WeeChat infolist "window".
  *
- * Note: result must be freed with function "weechat_infolist_free".
+ * Note: result must be freed after use with function weechat_infolist_free().
  */
 
 struct t_infolist *
diff --git a/src/plugins/plugin-script.c b/src/plugins/plugin-script.c
index 0e016ef79..ffb003a84 100644
--- a/src/plugins/plugin-script.c
+++ b/src/plugins/plugin-script.c
@@ -411,6 +411,8 @@ plugin_script_search_by_full_name (struct t_plugin_script *scripts,
 
 /*
  * Searches for path name of a script.
+ *
+ * Note: result must be freed after use.
  */
 
 char *
diff --git a/src/plugins/plugin.c b/src/plugins/plugin.c
index cee134d90..7bd76dc5b 100644
--- a/src/plugins/plugin.c
+++ b/src/plugins/plugin.c
@@ -285,7 +285,7 @@ plugin_check_autoload (const char *filename)
  * Returns arguments for plugins (only the relevant arguments for plugins,
  * arguments for WeeChat core not returned).
  *
- * Note: plugin_argv must be freed after use (with free()).
+ * Note: plugin_argv must be freed after use.
  */
 
 void
diff --git a/src/plugins/trigger/trigger-callback.c b/src/plugins/trigger/trigger-callback.c
index 50be1d985..cd89f6a2c 100644
--- a/src/plugins/trigger/trigger-callback.c
+++ b/src/plugins/trigger/trigger-callback.c
@@ -42,7 +42,7 @@ struct t_hashtable *trigger_callback_hashtable_options_regex = NULL;
  *
  * Returns a hashtable with the parsed message, or NULL if error.
  *
- * Note: the hashtable must be freed after use.
+ * Note: hashtable must be freed after use.
  */
 
 struct t_hashtable *