pidgin/pidgin

Convert docs from doxygen to gtk-doc format for gnt to gntprogressbar
gtkdoc-conversion
2014-02-02, Ankit Vani
5f7ccec14f33
Parents 8ee57c39c121
Children 2c495383415e
Convert docs from doxygen to gtk-doc format for gnt to gntprogressbar
17 files changed, 407 insertions(+), 240 deletions(-)
  • +52 -22
    finch/libgnt/gnt.h
  • +27 -23
    finch/libgnt/gntbindable.h
  • +43 -28
    finch/libgnt/gntbox.h
  • +5 -2
    finch/libgnt/gntbutton.h
  • +11 -6
    finch/libgnt/gntcheckbox.h
  • +8 -4
    finch/libgnt/gntclipboard.h
  • +25 -13
    finch/libgnt/gntcolors.h
  • +19 -10
    finch/libgnt/gntcombobox.h
  • +46 -31
    finch/libgnt/gntentry.h
  • +40 -24
    finch/libgnt/gntfilesel.h
  • +21 -13
    finch/libgnt/gntkeys.h
  • +11 -6
    finch/libgnt/gntlabel.h
  • +5 -2
    finch/libgnt/gntline.h
  • +18 -9
    finch/libgnt/gntmenu.h
  • +34 -23
    finch/libgnt/gntmenuitem.h
  • +11 -6
    finch/libgnt/gntmenuitemcheck.h
  • +31 -18
    finch/libgnt/gntprogressbar.h
    • --- a/finch/libgnt/gnt.h Sun Feb 02 01:21:37 2014 +0530
    +++ b/finch/libgnt/gnt.h Sun Feb 02 02:27:03 2014 +0530
    @@ -40,16 +40,22 @@
    #include "gntkeys.h"
    /**
    + * gnt_init:
    + *
    * Initialize GNT.
    */
    void gnt_init(void);
    /**
    + * gnt_main:
    + *
    * Start running the mainloop for gnt.
    */
    void gnt_main(void);
    /**
    + * gnt_ascii_only:
    + *
    * Check whether the terminal is capable of UTF8 display.
    *
    * Returns: %FALSE if the terminal is capable of drawing UTF-8, %TRUE otherwise.
    @@ -57,98 +63,116 @@
    gboolean gnt_ascii_only(void);
    /**
    + * gnt_window_present:
    + * @window: The window the present.
    + *
    * Present a window. If the event was triggered because of user interaction,
    * the window is moved to the foreground. Otherwise, the Urgent hint is set.
    *
    - * @window: The window the present.
    - *
    - * @since 2.0.0 (gnt), 2.1.0 (pidgin)
    + * Since: 2.0.0 (gnt), 2.1.0 (pidgin)
    */
    void gnt_window_present(GntWidget *window);
    /**
    + * gnt_screen_occupy:
    + *
    * @internal
    * Use #gnt_widget_show instead.
    */
    void gnt_screen_occupy(GntWidget *widget);
    /**
    + * gnt_screen_release:
    + *
    * @internal
    * Use #gnt_widget_hide instead.
    */
    void gnt_screen_release(GntWidget *widget);
    /**
    + * gnt_screen_update:
    + *
    * @internal
    * Use #gnt_widget_draw instead.
    */
    void gnt_screen_update(GntWidget *widget);
    /**
    - * Resize a widget.
    - *
    + * gnt_screen_resize_widget:
    * @widget: The widget to resize.
    * @width: The desired width.
    * @height: The desired height.
    + *
    + * Resize a widget.
    */
    void gnt_screen_resize_widget(GntWidget *widget, int width, int height);
    /**
    - * Move a widget.
    - *
    + * gnt_screen_move_widget:
    * @widget: The widget to move.
    * @x: The desired x-coordinate.
    * @y: The desired y-coordinate.
    + *
    + * Move a widget.
    */
    void gnt_screen_move_widget(GntWidget *widget, int x, int y);
    /**
    - * Rename a widget.
    - *
    + * gnt_screen_rename_widget:
    * @widget: The widget to rename.
    * @text: The new name for the widget.
    + *
    + * Rename a widget.
    */
    void gnt_screen_rename_widget(GntWidget *widget, const char *text);
    /**
    - * Check whether a widget has focus.
    + * gnt_widget_has_focus:
    + * @widget: The widget.
    *
    - * @widget: The widget.
    + * Check whether a widget has focus.
    *
    * Returns: %TRUE if the widget has the current focus, %FALSE otherwise.
    */
    gboolean gnt_widget_has_focus(GntWidget *widget);
    /**
    - * Set the URGENT hint for a widget.
    + * gnt_widget_set_urgent:
    + * @widget: The widget to set the URGENT hint for.
    *
    - * @widget: The widget to set the URGENT hint for.
    + * Set the URGENT hint for a widget.
    */
    void gnt_widget_set_urgent(GntWidget *widget);
    /**
    - * Register a global action.
    - *
    + * gnt_register_action:
    * @label: The user-visible label for the action.
    * @callback: The callback function for the action.
    + *
    + * Register a global action.
    */
    void gnt_register_action(const char *label, void (*callback)(void));
    /**
    - * Show a menu.
    + * gnt_screen_menu_show:
    + * @menu: The menu to display.
    *
    - * @menu: The menu to display.
    + * Show a menu.
    *
    * Returns: %TRUE if the menu is displayed, %FALSE otherwise (e.g., if another menu is currently displayed).
    */
    gboolean gnt_screen_menu_show(gpointer menu);
    /**
    + * gnt_quit:
    + *
    * Terminate the mainloop of gnt.
    */
    void gnt_quit(void);
    /**
    + * gnt_get_clipboard:
    + *
    * Get the global clipboard.
    *
    * Returns: The clipboard.
    @@ -156,22 +180,24 @@
    GntClipboard * gnt_get_clipboard(void);
    /**
    + * gnt_get_clipboard_string:
    + *
    * Get the string in the clipboard.
    *
    - * Returns: A copy of the string in the clipboard. The caller must @c g_free the string.
    + * Returns: A copy of the string in the clipboard. The caller must g_free() the string.
    */
    gchar * gnt_get_clipboard_string(void);
    /**
    - * Set the contents of the global clipboard.
    + * gnt_set_clipboard_string:
    + * @string: The new content of the new clipboard.
    *
    - * @string: The new content of the new clipboard.
    + * Set the contents of the global clipboard.
    */
    void gnt_set_clipboard_string(const gchar *string);
    /**
    - * Spawn a different application that will consume the console.
    - *
    + * gnt_giveup_console:
    * @wd: The working directory for the new application.
    * @argv: The argument vector.
    * @envp: The environment, or %NULL.
    @@ -181,6 +207,8 @@
    * @callback: The callback to call after the child exits.
    * @data: The data to pass to the callback.
    *
    + * Spawn a different application that will consume the console.
    + *
    * Returns: %TRUE if the child was successfully spawned, %FALSE otherwise.
    */
    gboolean gnt_giveup_console(const char *wd, char **argv, char **envp,
    @@ -188,6 +216,8 @@
    void (*callback)(int status, gpointer data), gpointer data);
    /**
    + * gnt_is_refugee:
    + *
    * Check whether a child process is in control of the current terminal.
    *
    * Returns: %TRUE if a child process (eg., PAGER) is occupying the current
    --- a/finch/libgnt/gntbindable.h Sun Feb 02 01:21:37 2014 +0530
    +++ b/finch/libgnt/gntbindable.h Sun Feb 02 02:27:03 2014 +0530
    @@ -66,11 +66,6 @@
    G_BEGIN_DECLS
    -/**
    - *
    - *
    - * Returns:
    - */
    GType gnt_bindable_get_gtype(void);
    /******************/
    @@ -105,84 +100,93 @@
    /*GntBindableAction *gnt_bindable_action_parse(const char *name);*/
    /**
    - * Free a bindable action.
    + * gnt_bindable_action_free:
    + * @action: The bindable action.
    *
    - * @action: The bindable action.
    + * Free a bindable action.
    */
    void gnt_bindable_action_free(GntBindableAction *action);
    /**
    - * Free a GntBindableActionParam.
    + * gnt_bindable_action_param_free:
    + * @param: The GntBindableActionParam to free.
    *
    - * @param: The GntBindableActionParam to free.
    + * Free a GntBindableActionParam.
    */
    void gnt_bindable_action_param_free(GntBindableActionParam *param);
    /**
    - * Register a bindable action for a class.
    - *
    + * gnt_bindable_class_register_action:
    * @klass: The class the binding is for.
    * @name: The name of the binding.
    * @callback: The callback for the binding.
    * @trigger: The default trigger for the binding, or %NULL, followed by a NULL-terminated
    * list of default parameters.
    + *
    + * Register a bindable action for a class.
    */
    void gnt_bindable_class_register_action(GntBindableClass *klass, const char *name, GntBindableActionCallback callback, const char *trigger, ...);
    /**
    - * Register a key-binding to an existing action.
    - *
    + * gnt_bindable_register_binding:
    * @klass: The class the binding is for.
    * @name: The name of the binding.
    * @trigger: A new trigger for the binding, followed by a %NULL-terminated list of parameters for the callback.
    + *
    + * Register a key-binding to an existing action.
    */
    void gnt_bindable_register_binding(GntBindableClass *klass, const char *name, const char *trigger, ...);
    /**
    - * Perform an action from a keybinding.
    - *
    + * gnt_bindable_perform_action_key:
    * @bindable: The bindable object.
    * @keys: The key to trigger the action.
    *
    + * Perform an action from a keybinding.
    + *
    * Returns: %TRUE if the action was performed successfully, %FALSE otherwise.
    */
    gboolean gnt_bindable_perform_action_key(GntBindable *bindable, const char *keys);
    /**
    - * Discover if a key is bound.
    - *
    + * gnt_bindable_check_key:
    * @bindable: The bindable object.
    * @keys: The key to check for.
    *
    + * Discover if a key is bound.
    + *
    * Returns: %TRUE if the the key has an action associated with it.
    */
    gboolean gnt_bindable_check_key(GntBindable *bindable, const char *keys);
    /**
    - * Perform an action on a bindable object.
    - *
    + * gnt_bindable_perform_action_named:
    * @bindable: The bindable object.
    * @name: The action to perform, followed by a %NULL-terminated list of parameters.
    *
    + * Perform an action on a bindable object.
    + *
    * Returns: %TRUE if the action was performed successfully, %FALSE otherwise.
    */
    gboolean gnt_bindable_perform_action_named(GntBindable *bindable, const char *name, ...) G_GNUC_NULL_TERMINATED;
    /**
    - * Returns a GntTree populated with "key" -> "binding" for the widget.
    + * gnt_bindable_bindings_view:
    + * @bind: The object to list the bindings for.
    *
    - * @bind: The object to list the bindings for.
    + * Returns a GntTree populated with "key" -> "binding" for the widget.
    *
    * Returns: The GntTree.
    */
    GntBindable * gnt_bindable_bindings_view(GntBindable *bind);
    /**
    + * gnt_bindable_build_help_window:
    + * @bindable: The object to list the bindings for.
    + *
    * Builds a window that list the key bindings for a GntBindable object.
    * From this window a user can select a listing to rebind a new key for the given action.
    *
    - * @bindable: The object to list the bindings for.
    - *
    * Returns: %TRUE
    */
    --- a/finch/libgnt/gntbox.h Sun Feb 02 01:21:37 2014 +0530
    +++ b/finch/libgnt/gntbox.h Sun Feb 02 02:27:03 2014 +0530
    @@ -88,6 +88,8 @@
    G_BEGIN_DECLS
    /**
    + * gnt_box_get_gtype:
    + *
    * The GType for GntBox.
    * Returns: The GType.
    */
    @@ -97,110 +99,123 @@
    #define gnt_hbox_new(homo) gnt_box_new(homo, FALSE)
    /**
    - * Create a new GntBox.
    - *
    + * gnt_box_new:
    * @homo: If %TRUE, all the widgets in it will have the same width (or height)
    * @vert: Whether the widgets in it should be stacked vertically (if %TRUE)
    * or horizontally (if %FALSE).
    *
    + * Create a new GntBox.
    + *
    * Returns: The new GntBox.
    */
    GntWidget * gnt_box_new(gboolean homo, gboolean vert);
    /**
    - * Add a widget in the box.
    - *
    + * gnt_box_add_widget:
    * @box: The box
    * @widget: The widget to add
    + *
    + * Add a widget in the box.
    */
    void gnt_box_add_widget(GntBox *box, GntWidget *widget);
    /**
    - * Set a title for the box.
    - *
    + * gnt_box_set_title:
    * @box: The box
    * @title: The title to set
    + *
    + * Set a title for the box.
    */
    void gnt_box_set_title(GntBox *box, const char *title);
    /**
    - * Set the padding to use between the widgets in the box.
    - *
    + * gnt_box_set_pad:
    * @box: The box
    * @pad: The padding to use
    + *
    + * Set the padding to use between the widgets in the box.
    */
    void gnt_box_set_pad(GntBox *box, int pad);
    /**
    + * gnt_box_set_toplevel:
    + * @box: The box
    + * @set: %TRUE if it's a toplevel box, %FALSE otherwise.
    + *
    * Set whether it's a toplevel box (ie, a window) or not. If a box is toplevel,
    * then it will show borders, the title (if set) and shadow (if enabled in
    - * @e .gntrc)
    - *
    - * @box: The box
    - * @set: %TRUE if it's a toplevel box, %FALSE otherwise.
    + * <filename>.gntrc</filename>)
    */
    void gnt_box_set_toplevel(GntBox *box, gboolean set);
    /**
    - * Reposition and refresh the widgets in the box.
    + * gnt_box_sync_children:
    + * @box: The box
    *
    - * @box: The box
    + * Reposition and refresh the widgets in the box.
    */
    void gnt_box_sync_children(GntBox *box);
    /**
    - * Set the alignment for the widgets in the box.
    - *
    + * gnt_box_set_alignment:
    * @box: The box
    * @alignment: The alignment to use
    + *
    + * Set the alignment for the widgets in the box.
    */
    void gnt_box_set_alignment(GntBox *box, GntAlignment alignment);
    /**
    - * Remove a widget from the box. Calling this does NOT destroy the removed widget.
    - *
    + * gnt_box_remove:
    * @box: The box
    * @widget: The widget to remove
    + *
    + * Remove a widget from the box. Calling this does NOT destroy the removed widget.
    */
    void gnt_box_remove(GntBox *box, GntWidget *widget);
    /**
    - * Remove all widgets from the box. This DOES destroy all widgets in the box.
    + * gnt_box_remove_all:
    + * @box: The box
    *
    - * @box: The box
    + * Remove all widgets from the box. This DOES destroy all widgets in the box.
    */
    void gnt_box_remove_all(GntBox *box);
    /**
    + * gnt_box_readjust:
    + * @box: The box
    + *
    * Readjust the size of each child widget, reposition the child widgets and
    * recalculate the size of the box.
    - *
    - * @box: The box
    */
    void gnt_box_readjust(GntBox *box);
    /**
    - * Set whether the widgets in the box should fill the empty spaces.
    - *
    + * gnt_box_set_fill:
    * @box: The box
    * @fill: Whether the child widgets should fill the empty space
    + *
    + * Set whether the widgets in the box should fill the empty spaces.
    */
    void gnt_box_set_fill(GntBox *box, gboolean fill);
    /**
    - * Move the focus from one widget to the other.
    - *
    + * gnt_box_move_focus:
    * @box: The box
    * @dir: The direction. If it's 1, then the focus is moved forwards, if it's
    * -1, the focus is moved backwards.
    + *
    + * Move the focus from one widget to the other.
    */
    void gnt_box_move_focus(GntBox *box, int dir);
    /**
    - * Give focus to a specific child widget.
    - *
    + * gnt_box_give_focus_to_child:
    * @box: The box
    * @widget: The child widget to give focus
    + *
    + * Give focus to a specific child widget.
    */
    void gnt_box_give_focus_to_child(GntBox *box, GntWidget *widget);
    --- a/finch/libgnt/gntbutton.h Sun Feb 02 01:21:37 2014 +0530
    +++ b/finch/libgnt/gntbutton.h Sun Feb 02 02:27:03 2014 +0530
    @@ -73,14 +73,17 @@
    G_BEGIN_DECLS
    /**
    + * gnt_button_get_gtype:
    + *
    * Returns: GType for Gntbutton
    */
    GType gnt_button_get_gtype(void);
    /**
    - * Create a new button.
    + * gnt_button_new:
    + * @text: The text for the button.
    *
    - * @text: The text for the button.
    + * Create a new button.
    *
    * Returns: The newly created button.
    */
    --- a/finch/libgnt/gntcheckbox.h Sun Feb 02 01:21:37 2014 +0530
    +++ b/finch/libgnt/gntcheckbox.h Sun Feb 02 02:27:03 2014 +0530
    @@ -68,31 +68,36 @@
    G_BEGIN_DECLS
    /**
    + * gnt_check_box_get_gtype:
    + *
    * Returns: GType for GntCheckBox
    */
    GType gnt_check_box_get_gtype(void);
    /**
    - * Create a new checkbox.
    + * gnt_check_box_new:
    + * @text: The text for the checkbox.
    *
    - * @text: The text for the checkbox.
    + * Create a new checkbox.
    *
    * Returns: The newly created checkbox.
    */
    GntWidget * gnt_check_box_new(const char *text);
    /**
    - * Set whether the checkbox should be checked or not.
    - *
    + * gnt_check_box_set_checked:
    * @box: The checkbox.
    * @set: %TRUE if the checkbox should be selected, %FALSE otherwise.
    + *
    + * Set whether the checkbox should be checked or not.
    */
    void gnt_check_box_set_checked(GntCheckBox *box, gboolean set);
    /**
    - * Return the checked state of the checkbox.
    + * gnt_check_box_get_checked:
    + * @box: The checkbox.
    *
    - * @box: The checkbox.
    + * Return the checked state of the checkbox.
    *
    * Returns: %TRUE if the checkbox is selected, %FALSE otherwise.
    */
    --- a/finch/libgnt/gntclipboard.h Sun Feb 02 01:21:37 2014 +0530
    +++ b/finch/libgnt/gntclipboard.h Sun Feb 02 02:27:03 2014 +0530
    @@ -60,14 +60,17 @@
    G_BEGIN_DECLS
    /**
    + * gnt_clipboard_get_gtype:
    + *
    * Returns: GType for GntClipboard.
    */
    GType gnt_clipboard_get_gtype(void);
    /**
    - * Get the current text from the clipboard.
    + * gnt_clipboard_get_string:
    + * @clip: The clipboard.
    *
    - * @clip: The clipboard.
    + * Get the current text from the clipboard.
    *
    * Returns: A copy of the string in the clipboard. The caller should free the
    * returned value.
    @@ -75,10 +78,11 @@
    gchar * gnt_clipboard_get_string(GntClipboard *clip);
    /**
    - * Set the text in the clipboard.
    - *
    + * gnt_clipboard_set_string:
    * @clip: The clipboard.
    * @string: New string for the clipboard.
    + *
    + * Set the text in the clipboard.
    */
    void gnt_clipboard_set_string(GntClipboard *clip, const gchar *string);
    --- a/finch/libgnt/gntcolors.h Sun Feb 02 01:21:37 2014 +0530
    +++ b/finch/libgnt/gntcolors.h Sun Feb 02 02:27:03 2014 +0530
    @@ -30,6 +30,8 @@
    #include <glib.h>
    /**
    + * GntColorType:
    + *
    * Different classes of colors.
    */
    typedef enum
    @@ -62,62 +64,72 @@
    };
    /**
    + * gnt_init_colors:
    + *
    * Initialize the colors.
    */
    void gnt_init_colors(void);
    /**
    + * gnt_uninit_colors:
    + *
    * Uninitialize the colors.
    */
    void gnt_uninit_colors(void);
    /**
    - * Parse color information from a file.
    + * gnt_colors_parse:
    + * @kfile: The file containing color information.
    *
    - * @kfile: The file containing color information.
    + * Parse color information from a file.
    */
    void gnt_colors_parse(GKeyFile *kfile);
    /**
    - * Parse color-pair information from a file.
    + * gnt_color_pairs_parse:
    + * @kfile: The file containing the color-pair information.
    *
    - * @kfile: The file containing the color-pair information.
    + * Parse color-pair information from a file.
    */
    void gnt_color_pairs_parse(GKeyFile *kfile);
    /**
    - * Parse a string color
    + * gnt_colors_get_color:
    + * @kfile: The string value
    *
    - * @kfile: The string value
    + * Parse a string color
    *
    * Returns: A color. For an unknown color name, returns -EINVAL.
    *
    - * @since 2.4.0
    + * Since: 2.4.0
    */
    int gnt_colors_get_color(char *key);
    /**
    + * gnt_color_pair:
    + * @color: The color code.
    + *
    * Return the appropriate character attribute for a specified color.
    * If the terminal doesn't have color support, this returns A_STANDOUT
    * when deemed appropriate.
    *
    - * @color: The color code.
    - *
    * Returns: A character attribute.
    *
    - * @since 2.3.0
    + * Since: 2.3.0
    */
    int gnt_color_pair(int color);
    /**
    - * Adds a color definition
    - *
    + * gnt_color_add_pair:
    * @fg: Foreground
    * @bg: Background
    *
    + * Adds a color definition
    + *
    * Returns: A color pair
    *
    - * @since 2.4.0
    + * Since: 2.4.0
    */
    int gnt_color_add_pair(int fg, int bg);
    +
    #endif
    --- a/finch/libgnt/gntcombobox.h Sun Feb 02 01:21:37 2014 +0530
    +++ b/finch/libgnt/gntcombobox.h Sun Feb 02 02:27:03 2014 +0530
    @@ -69,11 +69,15 @@
    G_BEGIN_DECLS
    /**
    + * gnt_combo_box_get_gtype:
    + *
    * Returns: Get the GType for GntComboBox
    */
    GType gnt_combo_box_get_gtype(void);
    /**
    + * gnt_combo_box_new:
    + *
    * Create a new GntComboBox
    *
    * Returns: A new GntComboBox
    @@ -81,43 +85,48 @@
    GntWidget * gnt_combo_box_new(void);
    /**
    - * Add an entry
    - *
    + * gnt_combo_box_add_data:
    * @box: The GntComboBox
    * @key: The data
    * @text: The text to display
    + *
    + * Add an entry
    */
    void gnt_combo_box_add_data(GntComboBox *box, gpointer key, const char *text);
    /**
    - * Remove an entry
    - *
    + * gnt_combo_box_remove:
    * @box: The GntComboBox
    * @key: The data to be removed
    + *
    + * Remove an entry
    */
    void gnt_combo_box_remove(GntComboBox *box, gpointer key);
    /**
    - * Remove all entries
    + * gnt_combo_box_remove_all:
    + * @box: The GntComboBox
    *
    - * @box: The GntComboBox
    + * Remove all entries
    */
    void gnt_combo_box_remove_all(GntComboBox *box);
    /**
    - * Get the data that is currently selected
    + * gnt_combo_box_get_selected_data:
    + * @box: The GntComboBox
    *
    - * @box: The GntComboBox
    + * Get the data that is currently selected
    *
    * Returns: The data of the currently selected entry
    */
    gpointer gnt_combo_box_get_selected_data(GntComboBox *box);
    /**
    - * Set the current selection to a specific entry
    - *
    + * gnt_combo_box_set_selected:
    * @box: The GntComboBox
    * @key: The data to be set to
    + *
    + * Set the current selection to a specific entry
    */
    void gnt_combo_box_set_selected(GntComboBox *box, gpointer key);
    --- a/finch/libgnt/gntentry.h Sun Feb 02 01:21:37 2014 +0530
    +++ b/finch/libgnt/gntentry.h Sun Feb 02 02:27:03 2014 +0530
    @@ -86,8 +86,8 @@
    gboolean word; /* Are the suggestions for only a word, or for the whole thing? */
    gboolean always; /* Should the list of suggestions show at all times, or only on tab-press? */
    GntWidget *ddown; /* The dropdown with the suggested list */
    - GntEntryKillRing *killring; /**< @since 2.3.0 */
    - GntEntrySearch *search; /**< @since 2.7.0 */
    + GntEntryKillRing *killring; /**< Since: 2.3.0 */
    + GntEntrySearch *search; /**< Since: 2.7.0 */
    };
    struct _GntEntryClass
    @@ -104,115 +104,130 @@
    G_BEGIN_DECLS
    /**
    + * gnt_entry_get_gtype:
    + *
    * Returns: GType for GntEntry.
    */
    GType gnt_entry_get_gtype(void);
    /**
    - * Create a new GntEntry.
    + * gnt_entry_new:
    + * @text: The text in the new entry box.
    *
    - * @text: The text in the new entry box.
    + * Create a new GntEntry.
    *
    * Returns: The newly created entry box.
    */
    GntWidget * gnt_entry_new(const char *text);
    /**
    - * Set the maximum length of the text in the entry box.
    - *
    + * gnt_entry_set_max:
    * @entry: The entry box.
    * @max: The maximum length for text. A value of 0 means infinite length.
    + *
    + * Set the maximum length of the text in the entry box.
    */
    void gnt_entry_set_max(GntEntry *entry, int max);
    /**
    - * Set the text in an entry box.
    - *
    + * gnt_entry_set_text:
    * @entry: The entry box.
    * @text: The text to set in the box.
    + *
    + * Set the text in an entry box.
    */
    void gnt_entry_set_text(GntEntry *entry, const char *text);
    /**
    - * Set flags an entry box.
    - *
    + * gnt_entry_set_flag:
    * @entry: The entry box.
    * @flag: The flags to set for the entry box.
    + *
    + * Set flags an entry box.
    */
    void gnt_entry_set_flag(GntEntry *entry, GntEntryFlag flag);
    /**
    - * Get the text in an entry box.
    + * gnt_entry_get_text:
    + * @entry: The entry box.
    *
    - * @entry: The entry box.
    + * Get the text in an entry box.
    *
    * Returns: The current text in the entry box.
    */
    const char *gnt_entry_get_text(GntEntry *entry);
    /**
    - * Clear the text in the entry box.
    + * gnt_entry_clear:
    + * @entry: The entry box.
    *
    - * @entry: The entry box.
    + * Clear the text in the entry box.
    */
    void gnt_entry_clear(GntEntry *entry);
    /**
    - * Set whether the text in the entry box should be masked for display.
    - *
    + * gnt_entry_set_masked:
    * @entry: The entry box.
    * @set: %TRUE if the text should be masked, %FALSE otherwise.
    + *
    + * Set whether the text in the entry box should be masked for display.
    */
    void gnt_entry_set_masked(GntEntry *entry, gboolean set);
    /**
    + * gnt_entry_add_to_history:
    + * @entry: The entry box.
    + * @text: A new entry for the history list.
    + *
    * Add a text to the history list for the text. The history length for the
    * entry box needs to be set first by gnt_entry_set_history_length.
    - *
    - * @entry: The entry box.
    - * @text: A new entry for the history list.
    */
    void gnt_entry_add_to_history(GntEntry *entry, const char *text);
    /**
    - * Set the length of history for the entry box.
    - *
    + * gnt_entry_set_history_length:
    * @entry: The entry box.
    * @num: The maximum length of the history, -1 for unlimited.
    + *
    + * Set the length of history for the entry box.
    */
    void gnt_entry_set_history_length(GntEntry *entry, int num);
    /**
    + * gnt_entry_set_word_suggest:
    + * @entry: The entry box.
    + * @word: %TRUE if the suggestions are for individual words, %FALSE otherwise.
    + *
    * Set whether the suggestions are for the entire entry box, or for each
    * individual word in the entry box.
    - *
    - * @entry: The entry box.
    - * @word: %TRUE if the suggestions are for individual words, %FALSE otherwise.
    */
    void gnt_entry_set_word_suggest(GntEntry *entry, gboolean word);
    /**
    + * gnt_entry_set_always_suggest:
    + * @entry: The entry box.
    + * @always: %TRUE if the suggestion list should always be displayed.
    + *
    * Set whether to always display the suggestions list, or only when the
    * tab-completion key is pressed (the TAB key, by default).
    - *
    - * @entry: The entry box.
    - * @always: %TRUE if the suggestion list should always be displayed.
    */
    void gnt_entry_set_always_suggest(GntEntry *entry, gboolean always);
    /**
    - * Add an item to the suggestion list.
    - *
    + * gnt_entry_add_suggest:
    * @entry: The entry box.
    * @text: An item to add to the suggestion list.
    + *
    + * Add an item to the suggestion list.
    */
    void gnt_entry_add_suggest(GntEntry *entry, const char *text);
    /**
    - * Remove an entry from the suggestion list.
    - *
    + * gnt_entry_remove_suggest:
    * @entry: The entry box.
    * @text: The item to remove from the suggestion list.
    + *
    + * Remove an entry from the suggestion list.
    */
    void gnt_entry_remove_suggest(GntEntry *entry, const char *text);
    --- a/finch/libgnt/gntfilesel.h Sun Feb 02 01:21:37 2014 +0530
    +++ b/finch/libgnt/gntfilesel.h Sun Feb 02 02:27:03 2014 +0530
    @@ -98,11 +98,15 @@
    G_BEGIN_DECLS
    /**
    + * gnt_file_sel_get_gtype:
    + *
    * Returns: GType for GntFileSel.
    */
    GType gnt_file_sel_get_gtype(void);
    /**
    + * gnt_file_sel_new:
    + *
    * Create a new file selector.
    *
    * Returns: The newly created file selector.
    @@ -110,45 +114,50 @@
    GntWidget * gnt_file_sel_new(void);
    /**
    - * Set the current location of the file selector.
    - *
    + * gnt_file_sel_set_current_location:
    * @sel: The file selector.
    * @path: The current path of the selector.
    *
    + * Set the current location of the file selector.
    + *
    * Returns: %TRUE if the current location was successfully changed, %FALSE otherwise.
    */
    gboolean gnt_file_sel_set_current_location(GntFileSel *sel, const char *path);
    /**
    - * Set wheter to only allow selecting directories.
    - *
    + * gnt_file_sel_set_dirs_only:
    * @sel: The file selector.
    * @dirs: %TRUE if only directories can be selected, %FALSE if files
    * can also be selected.
    + *
    + * Set wheter to only allow selecting directories.
    */
    void gnt_file_sel_set_dirs_only(GntFileSel *sel, gboolean dirs);
    /**
    - * Check whether the file selector allows only selecting directories.
    + * gnt_file_sel_get_dirs_only:
    + * @sel: The file selector.
    *
    - * @sel: The file selector.
    + * Check whether the file selector allows only selecting directories.
    *
    * Returns: %TRUE if only directories can be selected.
    */
    gboolean gnt_file_sel_get_dirs_only(GntFileSel *sel);
    /**
    - * Set whether a selected file must exist.
    - *
    + * gnt_file_sel_set_must_exist:
    * @sel: The file selector.
    * @must: %TRUE if the selected file must exist.
    + *
    + * Set whether a selected file must exist.
    */
    void gnt_file_sel_set_must_exist(GntFileSel *sel, gboolean must);
    /**
    - * Check whether the selector allows selecting non-existent files.
    + * gnt_file_sel_get_must_exist:
    + * @sel: The file selector.
    *
    - * @sel: The file selector.
    + * Check whether the selector allows selecting non-existent files.
    *
    * Returns: %TRUE if the selected file must exist, %FALSE if a non-existent
    * file can be selected.
    @@ -156,9 +165,10 @@
    gboolean gnt_file_sel_get_must_exist(GntFileSel *sel);
    /**
    - * Get the selected file in the selector.
    + * gnt_file_sel_get_selected_file:
    + * @sel: The file selector.
    *
    - * @sel: The file selector.
    + * Get the selected file in the selector.
    *
    * Returns: The path of the selected file. The caller should g_free the returned
    * string.
    @@ -166,9 +176,10 @@
    char * gnt_file_sel_get_selected_file(GntFileSel *sel);
    /**
    - * Get the list of selected files in the selector.
    + * gnt_file_sel_get_selected_multi_files:
    + * @sel: The file selector.
    *
    - * @sel: The file selector.
    + * Get the list of selected files in the selector.
    *
    * Returns: A list of paths for the selected files. The caller must g_free the
    * contents of the list, and g_list_free the list.
    @@ -176,43 +187,48 @@
    GList * gnt_file_sel_get_selected_multi_files(GntFileSel *sel);
    /**
    - * Allow selecting multiple files.
    - *
    + * gnt_file_sel_set_multi_select:
    * @sel: The file selector.
    * @set: %TRUE if selecting multiple files should be allowed.
    + *
    + * Allow selecting multiple files.
    */
    void gnt_file_sel_set_multi_select(GntFileSel *sel, gboolean set);
    /**
    - * Set the suggested file to have selected at startup.
    - *
    + * gnt_file_sel_set_suggested_filename:
    * @sel: The file selector.
    * @suggest: The suggested filename.
    + *
    + * Set the suggested file to have selected at startup.
    */
    void gnt_file_sel_set_suggested_filename(GntFileSel *sel, const char *suggest);
    /**
    - * Set custom functions to read the names of files.
    - *
    + * gnt_file_sel_set_read_fn:
    * @sel: The file selector.
    * @read_fn: The custom read function.
    + *
    + * Set custom functions to read the names of files.
    */
    void gnt_file_sel_set_read_fn(GntFileSel *sel, gboolean (*read_fn)(const char *path, GList **files, GError **error));
    /**
    - * Create a new GntFile.
    - *
    + * gnt_file_new:
    * @name: The name of the file.
    * @size: The size of the file.
    *
    + * Create a new GntFile.
    + *
    * Returns: The newly created GntFile.
    */
    GntFile* gnt_file_new(const char *name, unsigned long size);
    /**
    - * Create a new GntFile for a directory.
    + * gnt_file_new_dir:
    + * @name: The name of the directory.
    *
    - * @name: The name of the directory.
    + * Create a new GntFile for a directory.
    *
    * Returns: The newly created GntFile.
    */
    --- a/finch/libgnt/gntkeys.h Sun Feb 02 01:21:37 2014 +0530
    +++ b/finch/libgnt/gntkeys.h Sun Feb 02 02:27:03 2014 +0530
    @@ -30,7 +30,7 @@
    #include <curses.h>
    #include <term.h>
    -/**
    +/*
    * terminfo/termcap doesn't provide all the information that I want to use, eg.
    * ctrl-up, ctrl-down etc. So I am going to hard-code some of the information
    * for some popular $TERMs
    @@ -104,54 +104,62 @@
    #define GNT_KEY_F12 SAFE(key_f12)
    /**
    + * gnt_init_keys:
    + *
    * Initialize the keys.
    */
    void gnt_init_keys(void);
    /**
    + * gnt_keys_refine:
    + * @text: The input text to refine.
    + *
    * Refine input text. This usually looks at what the terminal claims it is,
    * and tries to change the text to work around some oft-broken terminfo entries.
    - *
    - * @text: The input text to refine.
    */
    void gnt_keys_refine(char *text);
    /**
    - * Translate a user-readable representation of an input to a machine-readable representation.
    + * gnt_key_translate:
    + * @name: The user-readable representation of an input (eg.: c-t)
    *
    - * @name: The user-readable representation of an input (eg.: c-t)
    + * Translate a user-readable representation of an input to a machine-readable representation.
    *
    * Returns: A machine-readable representation of the input.
    */
    const char *gnt_key_translate(const char *name);
    /**
    - * Translate a machine-readable representation of an input to a user-readable representation.
    + * gnt_key_lookup:
    + * @key: The machine-readable representation of an input.
    *
    - * @key: The machine-readable representation of an input.
    + * Translate a machine-readable representation of an input to a user-readable representation.
    *
    * Returns: A user-readable representation of the input (eg.: c-t).
    */
    const char *gnt_key_lookup(const char *key);
    /**
    - * Add a key combination to the internal key-tree.
    + * gnt_keys_add_combination:
    + * @key: The key to add
    *
    - * @key: The key to add
    + * Add a key combination to the internal key-tree.
    */
    void gnt_keys_add_combination(const char *key);
    /**
    - * Remove a key combination from the internal key-tree.
    + * gnt_keys_del_combination:
    + * @key: The key to remove.
    *
    - * @key: The key to remove.
    + * Remove a key combination from the internal key-tree.
    */
    void gnt_keys_del_combination(const char *key);
    /**
    - * Find a combination from the given string.
    + * gnt_keys_find_combination:
    + * @key: The input string.
    *
    - * @key: The input string.
    + * Find a combination from the given string.
    *
    * Returns: The number of bytes in the combination that starts at the beginning
    * of key (can be 0).
    --- a/finch/libgnt/gntlabel.h Sun Feb 02 01:21:37 2014 +0530
    +++ b/finch/libgnt/gntlabel.h Sun Feb 02 02:27:03 2014 +0530
    @@ -67,34 +67,39 @@
    G_BEGIN_DECLS
    /**
    + * gnt_label_get_gtype:
    + *
    * Returns: GType for GntLabel.
    */
    GType gnt_label_get_gtype(void);
    /**
    - * Create a new GntLabel.
    + * gnt_label_new:
    + * @text: The text of the label.
    *
    - * @text: The text of the label.
    + * Create a new GntLabel.
    *
    * Returns: The newly created label.
    */
    GntWidget * gnt_label_new(const char *text);
    /**
    - * Create a new label with specified text attributes.
    - *
    + * gnt_label_new_with_format:
    * @text: The text.
    * @flags: Text attributes for the text.
    *
    + * Create a new label with specified text attributes.
    + *
    * Returns: The newly created label.
    */
    GntWidget * gnt_label_new_with_format(const char *text, GntTextFormatFlags flags);
    /**
    - * Change the text of a label.
    - *
    + * gnt_label_set_text:
    * @label: The label.
    * @text: The new text to set in the label.
    + *
    + * Change the text of a label.
    */
    void gnt_label_set_text(GntLabel *label, const char *text);
    --- a/finch/libgnt/gntline.h Sun Feb 02 01:21:37 2014 +0530
    +++ b/finch/libgnt/gntline.h Sun Feb 02 02:27:03 2014 +0530
    @@ -67,6 +67,8 @@
    G_BEGIN_DECLS
    /**
    + * gnt_line_get_gtype:
    + *
    * Returns: GType for GntLine.
    */
    GType gnt_line_get_gtype(void);
    @@ -75,9 +77,10 @@
    #define gnt_vline_new() gnt_line_new(TRUE)
    /**
    - * Create new line
    + * gnt_line_new:
    + * @vertical: %TRUE if the line should be vertical, %FALSE for a horizontal line.
    *
    - * @vertical: %TRUE if the line should be vertical, %FALSE for a horizontal line.
    + * Create new line
    *
    * Returns: The newly created line.
    */
    --- a/finch/libgnt/gntmenu.h Sun Feb 02 01:21:37 2014 +0530
    +++ b/finch/libgnt/gntmenu.h Sun Feb 02 02:27:03 2014 +0530
    @@ -49,14 +49,18 @@
    #include "gntmenuitem.h"
    /**
    + * GntMenuType:
    + * @GNT_MENU_TOPLEVEL: Menu for a toplevel window
    + * @GNT_MENU_POPUP: A popup menu
    + *
    * A toplevel-menu is displayed at the top of the screen, and it spans accross
    * the entire width of the screen.
    * A popup-menu could be displayed, for example, as a context menu for widgets.
    */
    typedef enum
    {
    - GNT_MENU_TOPLEVEL = 1, /* Menu for a toplevel window */
    - GNT_MENU_POPUP, /* A popup menu */
    + GNT_MENU_TOPLEVEL = 1,
    + GNT_MENU_POPUP,
    } GntMenuType;
    struct _GntMenu
    @@ -86,36 +90,41 @@
    G_BEGIN_DECLS
    /**
    + * gnt_menu_get_gtype:
    + *
    * Returns: The GType for GntMenu.
    */
    GType gnt_menu_get_gtype(void);
    /**
    - * Create a new menu.
    + * gnt_menu_new:
    + * @type: The type of the menu, whether it's a toplevel menu or a popup menu.
    *
    - * @type: The type of the menu, whether it's a toplevel menu or a popup menu.
    + * Create a new menu.
    *
    * Returns: The newly created menu.
    */
    GntWidget * gnt_menu_new(GntMenuType type);
    /**
    - * Add an item to the menu.
    - *
    + * gnt_menu_add_item:
    * @menu: The menu.
    * @item: The item to add to the menu.
    + *
    + * Add an item to the menu.
    */
    void gnt_menu_add_item(GntMenu *menu, GntMenuItem *item);
    /**
    - * Return the GntMenuItem with the given ID.
    - *
    + * gnt_menu_get_item:
    * @menu: The menu.
    * @id: The ID for an item.
    *
    + * Return the GntMenuItem with the given ID.
    + *
    * Returns: The menuitem with the given ID, or %NULL.
    *
    - * @since 2.3.0
    + * Since: 2.3.0
    */
    GntMenuItem *gnt_menu_get_item(GntMenu *menu, const char *id);
    --- a/finch/libgnt/gntmenuitem.h Sun Feb 02 01:21:37 2014 +0530
    +++ b/finch/libgnt/gntmenuitem.h Sun Feb 02 02:27:03 2014 +0530
    @@ -87,97 +87,108 @@
    G_BEGIN_DECLS
    /**
    + * gnt_menuitem_get_gtype:
    + *
    * Returns: GType for GntMenuItem.
    */
    GType gnt_menuitem_get_gtype(void);
    /**
    - * Create a new menuitem.
    + * gnt_menuitem_new:
    + * @text: Label for the menuitem.
    *
    - * @text: Label for the menuitem.
    + * Create a new menuitem.
    *
    * Returns: The newly created menuitem.
    */
    GntMenuItem * gnt_menuitem_new(const char *text);
    /**
    - * Set a callback function for a menuitem.
    - *
    + * gnt_menuitem_set_callback:
    * @item: The menuitem.
    * @callback: The callback function.
    * @data: Data to send to the callback function.
    + *
    + * Set a callback function for a menuitem.
    */
    void gnt_menuitem_set_callback(GntMenuItem *item, GntMenuItemCallback callback, gpointer data);
    /**
    - * Set a submenu for a menuitem. A menuitem with a submenu cannot have a callback.
    - *
    + * gnt_menuitem_set_submenu:
    * @item: The menuitem.
    * @menu: The submenu.
    + *
    + * Set a submenu for a menuitem. A menuitem with a submenu cannot have a callback.
    */
    void gnt_menuitem_set_submenu(GntMenuItem *item, GntMenu *menu);
    /**
    - * Get the submenu for a menuitem.
    + * gnt_menuitem_get_submenu:
    + * @item: The menuitem.
    *
    - * @item: The menuitem.
    + * Get the submenu for a menuitem.
    *
    * Returns: The submenu, or %NULL.
    *
    - * @since 2.3.0
    + * Since: 2.3.0
    */
    GntMenu *gnt_menuitem_get_submenu(GntMenuItem *item);
    /**
    - * Set a trigger key for the item.
    - *
    + * gnt_menuitem_set_trigger:
    * @item: The menuitem
    * @trigger: The key that will trigger the item when the parent manu is visible
    + *
    + * Set a trigger key for the item.
    */
    void gnt_menuitem_set_trigger(GntMenuItem *item, char trigger);
    /**
    - * Get the trigger key for a menuitem.
    - *
    + * gnt_menuitem_get_trigger:
    * @item: The menuitem
    *
    - * Returns: The trigger key for the menuitem.
    + * Get the trigger key for a menuitem.
    *
    * @see gnt_menuitem_set_trigger
    + *
    + * Returns: The trigger key for the menuitem.
    */
    char gnt_menuitem_get_trigger(GntMenuItem *item);
    /**
    - * Set an ID for the menuitem.
    - *
    + * gnt_menuitem_set_id:
    * @item: The menuitem.
    * @id: The ID for the menuitem.
    *
    - * @since 2.3.0
    + * Set an ID for the menuitem.
    + *
    + * Since: 2.3.0
    */
    void gnt_menuitem_set_id(GntMenuItem *item, const char *id);
    /**
    - * Get the ID of the menuitem.
    + * gnt_menuitem_get_id:
    + * @item: The menuitem.
    *
    - * @item: The menuitem.
    + * Get the ID of the menuitem.
    *
    * Returns: The ID for the menuitem.
    *
    - * @since 2.3.0
    + * Since: 2.3.0
    */
    const char * gnt_menuitem_get_id(GntMenuItem *item);
    /**
    + * gnt_menuitem_activate:
    + * @item: The menuitem.
    + *
    * Activate a menuitem.
    * Activating the menuitem will first trigger the 'activate' signal for the
    * menuitem. Then the callback for the menuitem is triggered, if there is one.
    *
    - * @item: The menuitem.
    - *
    * Returns: Whether the callback for the menuitem was called.
    *
    - * @since 2.3.0
    + * Since: 2.3.0
    */
    gboolean gnt_menuitem_activate(GntMenuItem *item);
    --- a/finch/libgnt/gntmenuitemcheck.h Sun Feb 02 01:21:37 2014 +0530
    +++ b/finch/libgnt/gntmenuitemcheck.h Sun Feb 02 02:27:03 2014 +0530
    @@ -66,33 +66,38 @@
    G_BEGIN_DECLS
    /**
    + * gnt_menuitem_check_get_gtype:
    + *
    * Returns: GType for GntMenuItemCheck.
    */
    GType gnt_menuitem_check_get_gtype(void);
    /**
    - * Create a new menuitem.
    + * gnt_menuitem_check_new:
    + * @text: The text for the menuitem.
    *
    - * @text: The text for the menuitem.
    + * Create a new menuitem.
    *
    * Returns: The newly created menuitem.
    */
    GntMenuItem * gnt_menuitem_check_new(const char *text);
    /**
    - * Check whether the menuitem is checked or not.
    + * gnt_menuitem_check_get_checked:
    + * @item: The menuitem.
    *
    - * @item: The menuitem.
    + * Check whether the menuitem is checked or not.
    *
    * Returns: %TRUE if the item is checked, %FALSE otherwise.
    */
    gboolean gnt_menuitem_check_get_checked(GntMenuItemCheck *item);
    /**
    - * Set whether the menuitem is checked or not.
    - *
    + * gnt_menuitem_check_set_checked:
    * @item: The menuitem.
    * @set: %TRUE if the item should be checked, %FALSE otherwise.
    + *
    + * Set whether the menuitem is checked or not.
    */
    void gnt_menuitem_check_set_checked(GntMenuItemCheck *item, gboolean set);
    --- a/finch/libgnt/gntprogressbar.h Sun Feb 02 01:21:37 2014 +0530
    +++ b/finch/libgnt/gntprogressbar.h Sun Feb 02 02:27:03 2014 +0530
    @@ -60,70 +60,83 @@
    G_BEGIN_DECLS
    /**
    + * gnt_progress_bar_get_gtype:
    + *
    * Get the GType for GntProgressBar
    * Returns: The GType for GntProrgressBar
    - **/
    + */
    GType
    gnt_progress_bar_get_gtype (void);
    /**
    + * gnt_progress_bar_new:
    + *
    * Create a new GntProgressBar
    * Returns: The new GntProgressBar
    - **/
    + */
    GntWidget *
    gnt_progress_bar_new (void);
    /**
    - * Set the progress for a progress bar
    - *
    + * gnt_progress_bar_set_fraction:
    * @pbar: The GntProgressBar
    * @fraction: The value between 0 and 1 to display
    - **/
    + *
    + * Set the progress for a progress bar
    + */
    void
    gnt_progress_bar_set_fraction (GntProgressBar *pbar, gdouble fraction);
    /**
    - * Set the orientation for a progress bar
    - *
    + * gnt_progress_bar_set_orientation:
    * @pbar: The GntProgressBar
    * @orientation: The orientation to use
    - **/
    + *
    + * Set the orientation for a progress bar
    + */
    void
    gnt_progress_bar_set_orientation (GntProgressBar *pbar, GntProgressBarOrientation orientation);
    /**
    - * Controls whether the progress value is shown
    - *
    + * gnt_progress_bar_set_show_progress:
    * @pbar: The GntProgressBar
    * @show: A boolean indicating if the value is shown
    - **/
    + *
    + * Controls whether the progress value is shown
    + */
    void
    gnt_progress_bar_set_show_progress (GntProgressBar *pbar, gboolean show);
    /**
    + * gnt_progress_bar_get_fraction:
    + * @pbar: The GntProgressBar
    + *
    * Get the progress that is displayed
    *
    - * @pbar: The GntProgressBar
    * Returns: The progress displayed as a value between 0 and 1
    - **/
    + */
    gdouble
    gnt_progress_bar_get_fraction (GntProgressBar *pbar);
    /**
    + * gnt_progress_bar_get_orientation:
    + * @pbar: The GntProgressBar
    + *
    * Get the orientation for the progress bar
    *
    - * @pbar: The GntProgressBar
    * Returns: The current orientation of the progress bar
    - **/
    + */
    GntProgressBarOrientation
    gnt_progress_bar_get_orientation (GntProgressBar *pbar);
    /**
    + * gnt_progress_bar_get_show_progress:
    + * @pbar: The GntProgressBar
    + *
    * Get a boolean describing if the progress value is shown
    *
    - * @pbar: The GntProgressBar
    - * Returns: A boolean @c true if the progress value is shown, @c false otherwise.
    - **/
    + * Returns: %TRUE if the progress value is shown, %FALSE otherwise.
    + */
    gboolean
    gnt_progress_bar_get_show_progress (GntProgressBar *pbar);