core: reformat comments for functions

1 files changed, 73 insertions, 55 deletions

diff --git a/src/gui/gtk/gui-gtk-window.c b/src/gui/gtk/gui-gtk-window.c
index ad43e0036..ba912a866 100644
--- a/src/gui/gtk/gui-gtk-window.c
+++ b/src/gui/gtk/gui-gtk-window.c
@@ -45,7 +45,7 @@
 
 
 /*
- * gui_window_get_width: get screen width
+ * Gets screen width.
  */
 
 int
@@ -55,7 +55,7 @@ gui_window_get_width ()
 }
 
 /*
- * gui_window_get_height: get screen height
+ * Gets screen height.
  */
 
 int
@@ -65,7 +65,11 @@ gui_window_get_height ()
 }
 
 /*
- * gui_window_objects_init: init Gtk widgets
+ * Initializes Gtk widgets.
+ *
+ * Returns:
+ *   1: OK
+ *   0: error
  */
 
 int
@@ -85,7 +89,7 @@ gui_window_objects_init (struct t_gui_window *window)
 }
 
 /*
- * gui_window_objects_free: free Gtk widgets for a window
+ * Frees Gtk widgets for a window.
  */
 
 void
@@ -97,7 +101,7 @@ gui_window_objects_free (struct t_gui_window *window, int free_separators)
 }
 
 /*
- * gui_window_set_weechat_color: set WeeChat color for window
+ * Sets WeeChat color for window.
  */
 
 /* TODO: write this function for Gtk */
@@ -113,7 +117,7 @@ gui_window_set_weechat_color (WINDOW *window, int num_color)
 }*/
 
 /*
- * gui_window_calculate_pos_size: calculate position and size for a window & sub-win
+ * Calculates position and size for a window & sub-win.
  */
 
 void
@@ -124,7 +128,7 @@ gui_window_calculate_pos_size (struct t_gui_window *window)
 }
 
 /*
- * gui_window_draw_separators: draw window separation
+ * Draws window separation.
  */
 
 void
@@ -149,7 +153,7 @@ gui_window_draw_separators (struct t_gui_window *window)
 }
 
 /*
- * gui_window_redraw_buffer: redraw a buffer
+ * Redraws a buffer.
  */
 
 void
@@ -160,7 +164,7 @@ gui_window_redraw_buffer (struct t_gui_buffer *buffer)
 }
 
 /*
- * gui_window_redraw_all_buffers: redraw all buffers
+ * Redraws all buffers.
  */
 
 void
@@ -170,7 +174,7 @@ gui_window_redraw_all_buffers ()
 }
 
 /*
- * gui_window_switch: switch to another window
+ * Switches to another window.
  */
 
 void
@@ -193,7 +197,7 @@ gui_window_switch (struct t_gui_window *window)
 }
 
 /*
- * gui_window_switch_to_buffer: switch to another buffer
+ * Switches to another buffer.
  */
 
 void
@@ -258,7 +262,7 @@ gui_window_switch_to_buffer (struct t_gui_window *window,
 }
 
 /*
- * gui_window_page_up: display previous page on buffer
+ * Displays previous page on buffer.
  */
 
 void
@@ -279,7 +283,7 @@ gui_window_page_up (struct t_gui_window *window)
 }
 
 /*
- * gui_window_page_down: display next page on buffer
+ * Displays next page on buffer.
  */
 
 void
@@ -314,7 +318,7 @@ gui_window_page_down (struct t_gui_window *window)
 }
 
 /*
- * gui_window_scroll_up: display previous few lines in buffer
+ * Displays previous few lines in buffer.
  */
 
 void
@@ -336,7 +340,7 @@ gui_window_scroll_up (struct t_gui_window *window)
 }
 
 /*
- * gui_window_scroll_down: display next few lines in buffer
+ * Displays next few lines in buffer.
  */
 
 void
@@ -372,7 +376,7 @@ gui_window_scroll_down (struct t_gui_window *window)
 }
 
 /*
- * gui_window_scroll_top: scroll to top of buffer
+ * Scrolls to top of buffer.
  */
 
 void
@@ -390,7 +394,7 @@ gui_window_scroll_top (struct t_gui_window *window)
 }
 
 /*
- * gui_window_scroll_bottom: scroll to bottom of buffer
+ * Scrolls to bottom of buffer.
  */
 
 void
@@ -408,10 +412,13 @@ gui_window_scroll_bottom (struct t_gui_window *window)
 }
 
 /*
- * gui_window_auto_resize: auto-resize all windows, according to % of global size
- *                         This function is called after a terminal resize.
- *                         Returns 0 if ok, -1 if all window should be merged
- *                         (not enough space according to windows %)
+ * Auto-resizes all windows, according to % of global size.
+ *
+ * This function is called after a terminal resize.
+ *
+ * Returns:
+ *    0: OK
+ *   -1: all windows must be merged (not enough space)
  */
 
 int
@@ -463,7 +470,7 @@ gui_window_auto_resize (struct t_gui_window_tree *tree,
 }
 
 /*
- * gui_window_refresh_windows: auto resize and refresh all windows
+ * Auto-resizes and refreshes all windows.
  */
 
 void
@@ -478,7 +485,9 @@ gui_window_refresh_windows ()
 }
 
 /*
- * gui_window_split_horizontal: split a window horizontally
+ * Horizontally splits a window.
+ *
+ * Returns pointer to new window, NULL if error.
  */
 
 struct t_gui_window *
@@ -523,7 +532,9 @@ gui_window_split_horizontal (struct t_gui_window *window, int percentage)
 }
 
 /*
- * gui_window_split_vertical: split a window vertically
+ * Vertically splits a window.
+ *
+ * Returns pointer to new window, NULL if error.
  */
 
 struct t_gui_window *
@@ -570,7 +581,7 @@ gui_window_split_vertical (struct t_gui_window *window, int percentage)
 }
 
 /*
- * gui_window_resize: resize window
+ * Resizes window.
  */
 
 void
@@ -582,7 +593,7 @@ gui_window_resize (struct t_gui_window *window, int percentage)
 }
 
 /*
- * gui_window_resize_delta: resize window using delta percentage
+ * Resizes window using delta percentage.
  */
 
 void
@@ -594,7 +605,11 @@ gui_window_resize_delta (struct t_gui_window *window, int delta_percentage)
 }
 
 /*
- * gui_window_merge: merge window with its sister
+ * Merges window with its sister.
+ *
+ * Returns:
+ *   1: OK
+ *   0: error
  */
 
 int
@@ -639,7 +654,7 @@ gui_window_merge (struct t_gui_window *window)
 }
 
 /*
- * gui_window_merge_all: merge all windows into only one
+ * Merges all windows into only one.
  */
 
 void
@@ -650,12 +665,12 @@ gui_window_merge_all (struct t_gui_window *window)
 }
 
 /*
- * gui_window_side_by_side: return a code about position of 2 windows:
- *                          0 = they're not side by side
- *                          1 = side by side (win2 is over the win1)
- *                          2 = side by side (win2 on the right)
- *                          3 = side by side (win2 below win1)
- *                          4 = side by side (win2 on the left)
+ * Returns a code about position of 2 windows:
+ *   0 = they're not side by side
+ *   1 = side by side: win2 is over the win1
+ *   2 = side by side: win2 on the right
+ *   3 = side by side: win2 below win1
+ *   4 = side by side: win2 on the left
  */
 
 int
@@ -705,7 +720,7 @@ gui_window_side_by_side (struct t_gui_window *win1, struct t_gui_window *win2)
 }
 
 /*
- * gui_window_switch_up: search and switch to a window over current window
+ * Searches and switches to a window over current window.
  */
 
 void
@@ -728,7 +743,7 @@ gui_window_switch_up (struct t_gui_window *window)
 }
 
 /*
- * gui_window_switch_down: search and switch to a window below current window
+ * Searches and switches to a window below current window.
  */
 
 void
@@ -751,7 +766,7 @@ gui_window_switch_down (struct t_gui_window *window)
 }
 
 /*
- * gui_window_switch_left: search and switch to a window on the left of current window
+ * Searches and switches to a window on the left of current window.
  */
 
 void
@@ -774,7 +789,7 @@ gui_window_switch_left (struct t_gui_window *window)
 }
 
 /*
- * gui_window_switch_right: search and switch to a window on the right of current window
+ * Searches and switches to a window on the right of current window.
  */
 
 void
@@ -797,9 +812,11 @@ gui_window_switch_right (struct t_gui_window *window)
 }
 
 /*
- * gui_window_balance: balance windows (set all splits to 50%)
- *                     return 1 if some windows have been balanced
- *                            0 if nothing was changed
+ * Balance windows (set all splits to 50%).
+ *
+ * Returns:
+ *   1: some windows have been balanced
+ *   0: nothing was changed
  */
 
 int
@@ -812,12 +829,14 @@ gui_window_balance (struct t_gui_window_tree *tree)
 }
 
 /*
- * gui_window_swap: swap buffer of two windows
- *                  direction can be: 0 = auto (swap with sister)
- *                                    1 = window above
- *                                    2 = window on the right
- *                                    3 = window below
- *                                    4 = window on the left
+ * Swaps buffer of two windows.
+ *
+ * Argument "direction" can be:
+ *   0 = auto (swap with sister)
+ *   1 = window above
+ *   2 = window on the right
+ *   3 = window below
+ *   4 = window on the left
  */
 
 void
@@ -830,7 +849,7 @@ gui_window_swap (struct t_gui_window *window, int direction)
 }
 
 /*
- * gui_window_refresh_screen: called when term size is modified
+ * Called when terminal size is modified.
  */
 
 void
@@ -842,7 +861,7 @@ gui_window_refresh_screen (int full_refresh)
 }
 
 /*
- * gui_window_set_title: set terminal title
+ * Sets terminal title.
  */
 
 void
@@ -854,7 +873,7 @@ gui_window_set_title (const char *title)
 }
 
 /*
- * gui_window_send_clipboard: copy text to clipboard (sent to terminal)
+ * Copies text to clipboard (sent to terminal).
  */
 
 void
@@ -867,7 +886,7 @@ gui_window_send_clipboard (const char *storage_unit, const char *text)
 }
 
 /*
- * gui_window_set_bracketed_paste_mode: enable/disable bracketed paste mode
+ * Enables/disables bracketed paste mode.
  */
 
 void
@@ -879,7 +898,7 @@ gui_window_set_bracketed_paste_mode (int enable)
 }
 
 /*
- * gui_window_move_cursor: move cursor on screen (for cursor mode)
+ * Moves cursor on screen (for cursor mode).
  */
 
 void
@@ -889,7 +908,7 @@ gui_window_move_cursor ()
 }
 
 /*
- * gui_window_term_display_infos: display some infos about terminal and colors
+ * Displays some infos about terminal and colors.
  */
 
 void
@@ -899,8 +918,7 @@ gui_window_term_display_infos ()
 }
 
 /*
- * gui_window_objects_print_log: print Gtk objects infos in log
- *                               (usually for crash dump)
+ * Prints Gtk objects infos in WeeChat log file (usually for crash dump).
  */
 
 void