core: reformat comments for functions

11 files changed, 126 insertions, 88 deletions

diff --git a/src/plugins/xfer/xfer-buffer.c b/src/plugins/xfer/xfer-buffer.c
index 3fe3c9b4e..fed1d6cb0 100644
--- a/src/plugins/xfer/xfer-buffer.c
+++ b/src/plugins/xfer/xfer-buffer.c
@@ -38,7 +38,7 @@ int xfer_buffer_selected_line = 0;
 
 
 /*
- * xfer_buffer_refresh: update a xfer in buffer and update hotlist for xfer buffer
+ * Updates a xfer in buffer and updates hotlist for xfer buffer.
  */
 
 void
@@ -244,8 +244,7 @@ xfer_buffer_refresh (const char *hotlist)
 }
 
 /*
- * xfer_buffer_input_cb: callback called when user send data to xfer list
- *                       buffer
+ * Callback called when user send data to xfer list buffer.
  */
 
 int
@@ -309,7 +308,7 @@ xfer_buffer_input_cb (void *data, struct t_gui_buffer *buffer,
 }
 
 /*
- * xfer_buffer_close_cb: callback called when xfer buffer is closed
+ * Callback called when xfer buffer is closed.
  */
 
 int
@@ -325,7 +324,7 @@ xfer_buffer_close_cb (void *data, struct t_gui_buffer *buffer)
 }
 
 /*
- * xfer_buffer_open: open xfer buffer (to display list of xfer)
+ * Opens xfer buffer (to display list of xfer).
  */
 
 void
diff --git a/src/plugins/xfer/xfer-chat.c b/src/plugins/xfer/xfer-chat.c
index e13f41c54..4416e2381 100644
--- a/src/plugins/xfer/xfer-chat.c
+++ b/src/plugins/xfer/xfer-chat.c
@@ -35,7 +35,7 @@
 
 
 /*
- * xfer_chat_send: send data to remote host via xfer chat
+ * Sends data to remote host via xfer chat.
  */
 
 int
@@ -48,7 +48,7 @@ xfer_chat_send (struct t_xfer *xfer, const char *buffer, int size_buf)
 }
 
 /*
- * xfer_chat_sendf: send formatted data to remote host via DCC CHAT
+ * Sends formatted data to remote host via DCC CHAT.
  */
 
 void
@@ -86,7 +86,7 @@ xfer_chat_sendf (struct t_xfer *xfer, const char *format, ...)
 }
 
 /*
- * xfer_chat_recv_cb: receive data from xfer chat remote host
+ * Receives data from xfer chat remote host.
  */
 
 int
@@ -223,8 +223,7 @@ xfer_chat_recv_cb (void *arg_xfer, int fd)
 }
 
 /*
- * xfer_chat_buffer_input_cb: callback called when user send data to xfer chat
- *                            buffer
+ * Callback called when user sends data to xfer chat buffer.
  */
 
 int
@@ -265,8 +264,7 @@ xfer_chat_buffer_input_cb (void *data, struct t_gui_buffer *buffer,
 }
 
 /*
- * xfer_chat_close_buffer_cb: callback called when a buffer with direct chat
- *                            is closed
+ * Callback called when a buffer with direct chat is closed.
  */
 
 int
@@ -295,7 +293,7 @@ xfer_chat_buffer_close_cb (void *data, struct t_gui_buffer *buffer)
 }
 
 /*
- * xfer_chat_open_buffer: create buffer for DCC chat
+ * Creates buffer for DCC chat.
  */
 
 void
diff --git a/src/plugins/xfer/xfer-command.c b/src/plugins/xfer/xfer-command.c
index 02c834234..807079ad7 100644
--- a/src/plugins/xfer/xfer-command.c
+++ b/src/plugins/xfer/xfer-command.c
@@ -33,7 +33,7 @@
 
 
 /*
- * xfer_command_me: send a ctcp action to remote host
+ * Callback for command "/me": sends a ctcp action to remote host.
  */
 
 int
@@ -76,7 +76,7 @@ xfer_command_me (void *data, struct t_gui_buffer *buffer, int argc,
 }
 
 /*
- * xfer_command_xfer_list: list xfer
+ * Displays a list of xfer.
  */
 
 void
@@ -193,7 +193,7 @@ xfer_command_xfer_list (int full)
 }
 
 /*
- * xfer_command_xfer: command /xfer
+ * Callback for command "/xfer".
  */
 
 int
@@ -245,7 +245,7 @@ xfer_command_xfer (void *data, struct t_gui_buffer *buffer, int argc,
 }
 
 /*
- * xfer_command_init: add /xfer command
+ * Hooks commands.
  */
 
 void
diff --git a/src/plugins/xfer/xfer-completion.c b/src/plugins/xfer/xfer-completion.c
index 117bfeb97..d537c3c51 100644
--- a/src/plugins/xfer/xfer-completion.c
+++ b/src/plugins/xfer/xfer-completion.c
@@ -31,7 +31,7 @@
 
 
 /*
- * xfer_completion_nick_cb: callback for completion with nick
+ * Adds nicks to completion list.
  */
 
 int
@@ -64,7 +64,7 @@ xfer_completion_nick_cb (void *data, const char *completion_item,
 }
 
 /*
- * xfer_completion_init: init completion for xfer plugin
+ * Hooks completion.
  */
 
 void
diff --git a/src/plugins/xfer/xfer-config.c b/src/plugins/xfer/xfer-config.c
index 7fed0c78d..ebbd88cd2 100644
--- a/src/plugins/xfer/xfer-config.c
+++ b/src/plugins/xfer/xfer-config.c
@@ -67,8 +67,7 @@ struct t_config_option *xfer_config_file_auto_accept_chats;
 
 
 /*
- * xfer_config_refresh_cb: callback called when user changes xfer option that
- *                         needs a refresh of xfer list
+ * Callback for changes on an option that requires a refresh of xfer list.
  */
 
 void
@@ -83,7 +82,7 @@ xfer_config_refresh_cb (void *data, struct t_config_option *option)
 }
 
 /*
- * xfer_config_reload: reload xfer configuration file
+ * Reloads xfer configuration file.
  */
 
 int
@@ -96,8 +95,11 @@ xfer_config_reload (void *data, struct t_config_file *config_file)
 }
 
 /*
- * xfer_config_init: init xfer configuration file
- *                   return: 1 if ok, 0 if error
+ * Initializes xfer configuration file.
+ *
+ * Returns:
+ *   1: OK
+ *   0: error
  */
 
 int
@@ -309,7 +311,7 @@ xfer_config_init ()
 }
 
 /*
- * xfer_config_read: read xfer configuration file
+ * Reads xfer configuration file.
  */
 
 int
@@ -319,7 +321,7 @@ xfer_config_read ()
 }
 
 /*
- * xfer_config_write: write xfer configuration file
+ * Writes xfer configuration file.
  */
 
 int
diff --git a/src/plugins/xfer/xfer-dcc.c b/src/plugins/xfer/xfer-dcc.c
index 4885c4fdb..fc8c702c4 100644
--- a/src/plugins/xfer/xfer-dcc.c
+++ b/src/plugins/xfer/xfer-dcc.c
@@ -40,7 +40,7 @@
 
 
 /*
- * xfer_dcc_send_file_child: child process for sending file with DCC protocol
+ * Child process for sending file with DCC protocol.
  */
 
 void
@@ -175,7 +175,7 @@ xfer_dcc_send_file_child (struct t_xfer *xfer)
 }
 
 /*
- * xfer_dcc_recv_file_child: child process for receiving file
+ * Child process for receiving file with DCC protocol.
  */
 
 void
diff --git a/src/plugins/xfer/xfer-file.c b/src/plugins/xfer/xfer-file.c
index f56f7a2a4..e8338e010 100644
--- a/src/plugins/xfer/xfer-file.c
+++ b/src/plugins/xfer/xfer-file.c
@@ -39,8 +39,11 @@
 
 
 /*
- * xfer_file_resume: resume a download
- *                   return 1 if ok, 0 if not resumable
+ * Resumes a download.
+ *
+ * Returns:
+ *   1: OK
+ *   0: not resumable
  */
 
 int
@@ -70,9 +73,10 @@ xfer_file_resume (struct t_xfer *xfer, const char *filename)
 }
 
 /*
- * xfer_file_find_filename: find local filename for a xfer
- *                          if type if file/recv, add a suffix (like .1) if needed
- *                          if download is resumable, set "start_resume" to good value
+ * Searches for local filename for a xfer.
+ *
+ * If type is file/recv, adds a suffix (like .1) if needed.
+ * If download is resumable, sets "start_resume" to good value.
  */
 
 void
@@ -169,7 +173,7 @@ xfer_file_find_filename (struct t_xfer *xfer)
 }
 
 /*
- * xfer_file_calculate_speed: calculate xfer speed (for files only)
+ * Calculates xfer speed (for files only).
  */
 
 void
diff --git a/src/plugins/xfer/xfer-info.c b/src/plugins/xfer/xfer-info.c
index 80afd31cd..9276bd452 100644
--- a/src/plugins/xfer/xfer-info.c
+++ b/src/plugins/xfer/xfer-info.c
@@ -29,7 +29,7 @@
 
 
 /*
- * xfer_info_get_infolist_cb: callback called when xfer infolist is asked
+ * Returns infolist with xfer info.
  */
 
 struct t_infolist *
@@ -85,13 +85,12 @@ xfer_info_get_infolist_cb (void *data, const char *infolist_name,
 }
 
 /*
- * xfer_info_init: initialize info and infolist hooks for xfer plugin
+ * Hooks infolist.
  */
 
 void
 xfer_info_init ()
 {
-    /* xfer infolist hooks */
     weechat_hook_infolist ("xfer", N_("list of xfer"),
                            N_("xfer pointer (optional)"),
                            NULL,
diff --git a/src/plugins/xfer/xfer-network.c b/src/plugins/xfer/xfer-network.c
index e33612f67..78dc2b019 100644
--- a/src/plugins/xfer/xfer-network.c
+++ b/src/plugins/xfer/xfer-network.c
@@ -43,8 +43,11 @@
 
 
 /*
- * xfer_network_create_pipe: create pipe for communication with child process
- *                           return 1 if ok, 0 if error
+ * Creates pipe for communication with child process.
+ *
+ * Returns:
+ *   1: OK
+ *   0: error
  */
 
 int
@@ -69,7 +72,7 @@ xfer_network_create_pipe (struct t_xfer *xfer)
 }
 
 /*
- * xfer_network_write_pipe: write data into pipe
+ * Writes data into pipe.
  */
 
 void
@@ -85,7 +88,7 @@ xfer_network_write_pipe (struct t_xfer *xfer, int status, int error)
 }
 
 /*
- * xfer_network_child_read_cb: read data from child via pipe
+ * Reads data from child via pipe.
  */
 
 int
@@ -174,7 +177,7 @@ xfer_network_child_read_cb (void *arg_xfer, int fd)
 }
 
 /*
- * xfer_network_send_file_fork: fork process for sending file
+ * Forks process for sending file.
  */
 
 void
@@ -242,7 +245,7 @@ xfer_network_send_file_fork (struct t_xfer *xfer)
 }
 
 /*
- * xfer_network_recv_file_fork: fork process for receiving file
+ * Forks process for receiving file.
  */
 
 void
@@ -300,7 +303,7 @@ xfer_network_recv_file_fork (struct t_xfer *xfer)
 }
 
 /*
- * xfer_network_child_kill: kill child process and close pipe
+ * Kills child process and closes pipe.
  */
 
 void
@@ -328,7 +331,7 @@ xfer_network_child_kill (struct t_xfer *xfer)
 }
 
 /*
- * xfer_network_fd_cb: callback called when data is available on xfer socket
+ * Callback called when data is available on xfer socket.
  */
 
 int
@@ -437,8 +440,8 @@ xfer_network_fd_cb (void *arg_xfer, int fd)
 }
 
 /*
- * xfer_network_timer_cb: callback called to check if there's a timeout for xfer
- *                        (called only one time for xfer)
+ * Callback called to check if there's a timeout for xfer (called only one time
+ * for xfer).
  */
 
 int
@@ -466,7 +469,11 @@ xfer_network_timer_cb (void *arg_xfer, int remaining_calls)
 }
 
 /*
- * xfer_network_connect: connect to another host
+ * Connects to another host.
+ *
+ * Returns:
+ *   1: OK
+ *   0: error
  */
 
 int
@@ -537,7 +544,7 @@ xfer_network_connect (struct t_xfer *xfer)
 }
 
 /*
- * xfer_network_connect_init: connect to sender and init file or chat
+ * Connects to sender and initializes file or chat.
  */
 
 void
@@ -567,7 +574,7 @@ xfer_network_connect_init (struct t_xfer *xfer)
 }
 
 /*
- * xfer_network_accept: accept a xfer file or chat request
+ * Accepts a xfer file or chat request.
  */
 
 void
diff --git a/src/plugins/xfer/xfer-upgrade.c b/src/plugins/xfer/xfer-upgrade.c
index 3327d878c..fe0137e10 100644
--- a/src/plugins/xfer/xfer-upgrade.c
+++ b/src/plugins/xfer/xfer-upgrade.c
@@ -31,7 +31,11 @@
 
 
 /*
- * xfer_upgrade_save_xfers: save xfers info to upgrade file
+ * Saves xfers info to upgrade file.
+ *
+ * Returns:
+ *   1: OK
+ *   0: error
  */
 
 int
@@ -43,8 +47,11 @@ xfer_upgrade_save_xfers (struct t_upgrade_file *upgrade_file)
 }
 
 /*
- * xfer_upgrade_save: save upgrade file
- *                    return 1 if ok, 0 if error
+ * Saves upgrade file.
+ *
+ * Returns:
+ *   1: OK
+ *   0: error
  */
 
 int
@@ -65,8 +72,8 @@ xfer_upgrade_save ()
 }
 
 /*
- * xfer_upgrade_set_buffer_callbacks: restore buffers callbacks (input and
- *                                    close) for buffers created by xfer plugin
+ * Restores buffers callbacks (input and close) for buffers created by xfer
+ * plugin.
  */
 
 void
@@ -97,7 +104,7 @@ xfer_upgrade_set_buffer_callbacks ()
 }
 
 /*
- * xfer_upgrade_read_cb: read callback for xfer upgrade file
+ * Reads callback for xfer upgrade file.
  */
 
 int
@@ -116,8 +123,11 @@ xfer_upgrade_read_cb (void *data,
 }
 
 /*
- * xfer_upgrade_load: load upgrade file
- *                    return 1 if ok, 0 if error
+ * Loads upgrade file.
+ *
+ * Returns:
+ *   1: OK
+ *   0: error
  */
 
 int
diff --git a/src/plugins/xfer/xfer.c b/src/plugins/xfer/xfer.c
index 8bc7b071b..f9f099b4a 100644
--- a/src/plugins/xfer/xfer.c
+++ b/src/plugins/xfer/xfer.c
@@ -78,9 +78,11 @@ void xfer_disconnect_all ();
 
 
 /*
- * xfer_valid: check if a xfer pointer exists
- *             return 1 if xfer exists
- *                    0 if xfer is not found
+ * Checks if a xfer pointer is valid.
+ *
+ * Returns:
+ *   1: xfer exists
+ *   0: xfer does not exist
  */
 
 int
@@ -103,7 +105,7 @@ xfer_valid (struct t_xfer *xfer)
 }
 
 /*
- * xfer_signal_upgrade_cb: callback for "upgrade" signal
+ * Callback for signal "upgrade".
  */
 
 int
@@ -125,7 +127,7 @@ xfer_signal_upgrade_cb (void *data, const char *signal, const char *type_data,
 
 
 /*
- * xfer_create_directories: create directories for xfer plugin
+ * Creates directories for xfer plugin.
  */
 
 void
@@ -150,8 +152,9 @@ xfer_create_directories ()
 }
 
 /*
- * xfer_search_type: search xfer type with a string
- *                   return -1 if not found
+ * Searches for xfer type.
+ *
+ * Returns index of type in enum t_xfer_type, -1 if not found.
  */
 
 int
@@ -170,8 +173,9 @@ xfer_search_type (const char *type)
 }
 
 /*
- * xfer_search_protocol: search xfer protocol with a string
- *                       return -1 if not found
+ * Searches for xfer protocol.
+ *
+ * Returns index of protocol in enum t_xfer_protocol, -1 if not found.
  */
 
 int
@@ -190,7 +194,9 @@ xfer_search_protocol (const char *protocol)
 }
 
 /*
- * xfer_search: search a xfer
+ * Searches for a xfer.
+ *
+ * Returns pointer to xfer found, NULL if not found.
  */
 
 struct t_xfer *
@@ -214,7 +220,9 @@ xfer_search (const char *plugin_name, const char *plugin_id, enum t_xfer_type ty
 }
 
 /*
- * xfer_search_by_number: search a xfer by number (first xfer is 0)
+ * Searches for a xfer by number (first xfer is 0).
+ *
+ * Returns pointer to xfer found, NULL if not found.
  */
 
 struct t_xfer *
@@ -236,7 +244,9 @@ xfer_search_by_number (int number)
 }
 
 /*
- * xfer_search_by_buffer: search a xfer by buffer (for chat only)
+ * Searches for a xfer by buffer (for chat only).
+ *
+ * Returns pointer to xfer found, NULL if not found.
  */
 
 struct t_xfer *
@@ -258,7 +268,7 @@ xfer_search_by_buffer (struct t_gui_buffer *buffer)
 }
 
 /*
- * xfer_close: close a xfer
+ * Closes a xfer.
  */
 
 void
@@ -347,7 +357,7 @@ xfer_close (struct t_xfer *xfer, enum t_xfer_status status)
 }
 
 /*
- * xfer_disconnect_all: disconnect all active xfer (with a socket)
+ * Disconnects all active xfer (with a socket).
  */
 
 void
@@ -376,8 +386,11 @@ xfer_disconnect_all ()
 }
 
 /*
- * xfer_port_in_use: return 1 if a port is in used
- *                   (by an active or connecting xfer)
+ * Checks if a port is in used.
+ *
+ * Returns:
+ *   1: port is in used (by an active or connecting xfer)
+ *   0: port is not in used
  */
 
 int
@@ -397,7 +410,7 @@ xfer_port_in_use (int port)
 }
 
 /*
- * xfer_send_signal: send a signal for a xfer
+ * Sends a signal for a xfer.
  */
 
 void
@@ -439,7 +452,9 @@ xfer_send_signal (struct t_xfer *xfer, const char *signal)
 }
 
 /*
- * xfer_alloc: allocate a new xfer
+ * Allocates a new xfer.
+ *
+ * Returns pointer to new xfer, NULL if error.
  */
 
 struct t_xfer *
@@ -506,7 +521,9 @@ xfer_alloc ()
 }
 
 /*
- * xfer_new: add a xfer to list
+ * Adds a xfer to list.
+ *
+ * Returns pointer to new xfer, NULL if error.
  */
 
 struct t_xfer *
@@ -674,7 +691,7 @@ xfer_new (const char *plugin_name, const char *plugin_id,
 }
 
 /*
- * xfer_free: free xfer struct and remove it from list
+ * Frees xfer struct and removes it from list.
  */
 
 void
@@ -726,7 +743,7 @@ xfer_free (struct t_xfer *xfer)
 }
 
 /*
- * xfer_add_cb: callback for "xfer_add" signal
+ * Callback for signal "xfer_add".
  */
 
 int
@@ -1089,7 +1106,7 @@ error:
 }
 
 /*
- * xfer_start_resume_cb: callback called when resume is accepted by sender
+ * Callback called when resume is accepted by sender.
  */
 
 int
@@ -1173,8 +1190,7 @@ error:
 }
 
 /*
- * xfer_accept_resume_cb: callback called when sender receives resume request
- *                        from recever
+ * Callback called when sender receives resume request from receiver.
  */
 
 int
@@ -1265,8 +1281,11 @@ error:
 }
 
 /*
- * xfer_add_to_infolist: add a xfer in an infolist
- *                       return 1 if ok, 0 if error
+ * Adds a xfer in an infolist.
+ *
+ * Returns:
+ *   1: OK
+ *   0: error
  */
 
 int
@@ -1379,7 +1398,7 @@ xfer_add_to_infolist (struct t_infolist *infolist, struct t_xfer *xfer)
 }
 
 /*
- * xfer_print_log: print xfer infos in log (usually for crash dump)
+ * Prints xfer infos in WeeChat log file (usually for crash dump).
  */
 
 void
@@ -1442,7 +1461,7 @@ xfer_print_log ()
 }
 
 /*
- * xfer_debug_dump_cb: callback for "debug_dump" signal
+ * Callback for signal "debug_dump".
  */
 
 int
@@ -1472,7 +1491,7 @@ xfer_debug_dump_cb (void *data, const char *signal, const char *type_data,
 }
 
 /*
- * weechat_plugin_init: initialize xfer plugin
+ * Initializes xfer plugin.
  */
 
 int
@@ -1519,7 +1538,7 @@ weechat_plugin_init (struct t_weechat_plugin *plugin, int argc, char *argv[])
 }
 
 /*
- * weechat_plugin_end: end xfer plugin
+ * Ends xfer plugin.
  */
 
 int