qulogic/libgnt

Convert docs from doxygen to gtk-doc format for gnt-skel to gntws
gtkdoc-conversion
2014-02-02, Ankit Vani
aec03918183d
Parents 26a2dfe7cedf
Children a63e9aaeb0b7b06eb32f2de3
Convert docs from doxygen to gtk-doc format for gnt-skel to gntws
10 files changed, 559 insertions(+), 353 deletions(-)
  • +0 -10
    gnt-skel.h
  • +39 -30
    gntslider.h
  • +39 -18
    gntstyle.h
  • +52 -34
    gnttextview.h
  • +184 -122
    gnttree.h
  • +36 -31
    gntutils.h
  • +64 -28
    gntwidget.h
  • +22 -13
    gntwindow.h
  • +80 -37
    gntwm.h
  • +43 -30
    gntws.h
    • --- a/gnt-skel.h Sun Feb 02 02:27:03 2014 +0530
    +++ b/gnt-skel.h Sun Feb 02 03:34:37 2014 +0530
    @@ -60,18 +60,8 @@
    G_BEGIN_DECLS
    -/**
    - *
    - *
    - * Returns:
    - */
    GType gnt_skel_get_gtype(void);
    -/**
    - *
    - *
    - * Returns:
    - */
    GntWidget * gnt_skel_new();
    G_END_DECLS
    --- a/gntslider.h Sun Feb 02 02:27:03 2014 +0530
    +++ b/gntslider.h Sun Feb 02 03:34:37 2014 +0530
    @@ -74,9 +74,11 @@
    G_BEGIN_DECLS
    /**
    + * gnt_slider_get_gtype:
    + *
    * Returns: The GType for GntSlider
    *
    - * @since 2.0.0 (gnt), 2.1.0 (pidgin)
    + * Since: 2.0.0 (gnt), 2.1.0 (pidgin)
    */
    GType gnt_slider_get_gtype(void);
    @@ -84,103 +86,110 @@
    #define gnt_vslider_new(max, min) gnt_slider_new(TRUE, max, min)
    /**
    - * Create a new slider.
    - *
    + * gnt_slider_new:
    * @orient: A vertical slider is created if %TRUE, otherwise the slider is horizontal.
    * @max: The maximum value for the slider
    * @min: The minimum value for the slider
    *
    + * Create a new slider.
    + *
    * Returns: The newly created slider
    *
    - * @since 2.0.0 (gnt), 2.1.0 (pidgin)
    + * Since: 2.0.0 (gnt), 2.1.0 (pidgin)
    */
    GntWidget * gnt_slider_new(gboolean orient, int max, int min);
    /**
    - * Set the range of the slider.
    - *
    + * gnt_slider_set_range:
    * @slider: The slider
    * @max: The maximum value
    * @min: The minimum value
    *
    - * @since 2.0.0 (gnt), 2.1.0 (pidgin)
    + * Set the range of the slider.
    + *
    + * Since: 2.0.0 (gnt), 2.1.0 (pidgin)
    */
    void gnt_slider_set_range(GntSlider *slider, int max, int min);
    /**
    - * Sets the amount of change at each step.
    - *
    + * gnt_slider_set_step:
    * @slider: The slider
    * @step: The amount for each step
    *
    - * @since 2.0.0 (gnt), 2.1.0 (pidgin)
    + * Sets the amount of change at each step.
    + *
    + * Since: 2.0.0 (gnt), 2.1.0 (pidgin)
    */
    void gnt_slider_set_step(GntSlider *slider, int step);
    /**
    - * Sets the amount of change a small step.
    - *
    + * gnt_slider_set_small_step:
    * @slider: The slider
    * @step: The amount for a small step (for the slider)
    *
    - * @since 2.2.0
    + * Sets the amount of change a small step.
    + *
    + * Since: 2.2.0
    */
    void gnt_slider_set_small_step(GntSlider *slider, int step);
    /**
    - * Sets the amount of change a large step.
    - *
    + * gnt_slider_set_large_step:
    * @slider: The slider
    * @step: The amount for a large step (for the slider)
    *
    - * @since 2.2.0
    + * Sets the amount of change a large step.
    + *
    + * Since: 2.2.0
    */
    void gnt_slider_set_large_step(GntSlider *slider, int step);
    /**
    - * Advance the slider forward or backward.
    - *
    + * gnt_slider_advance_step:
    * @slider: The slider
    * @steps: The number of amounts to change, positive to change
    * forward, negative to change backward
    *
    + * Advance the slider forward or backward.
    + *
    * Returns: The value of the slider after the change
    *
    - * @since 2.0.0 (gnt), 2.1.0 (pidgin)
    + * Since: 2.0.0 (gnt), 2.1.0 (pidgin)
    */
    int gnt_slider_advance_step(GntSlider *slider, int steps);
    /**
    - * Set the current value for the slider.
    - *
    + * gnt_slider_set_value:
    * @slider: The slider
    * @value: The current value
    *
    - * @since 2.0.0 (gnt), 2.1.0 (pidgin)
    + * Set the current value for the slider.
    + *
    + * Since: 2.0.0 (gnt), 2.1.0 (pidgin)
    */
    void gnt_slider_set_value(GntSlider *slider, int value);
    /**
    + * gnt_slider_get_value:
    + * @slider: The slider
    + *
    * Get the current value for the slider.
    *
    - * @slider: The slider
    - *
    - *
    - * @since 2.0.0 (gnt), 2.1.0 (pidgin)
    + * Since: 2.0.0 (gnt), 2.1.0 (pidgin)
    */
    int gnt_slider_get_value(GntSlider *slider);
    /**
    - * Update a label with the value of the slider whenever the value changes.
    - *
    + * gnt_slider_reflect_label:
    * @slider: The slider
    * @label: The label to update
    *
    - * @since 2.0.0 (gnt), 2.1.0 (pidgin)
    + * Update a label with the value of the slider whenever the value changes.
    + *
    + * Since: 2.0.0 (gnt), 2.1.0 (pidgin)
    */
    void gnt_slider_reflect_label(GntSlider *slider, GntLabel *label);
    -
    G_END_DECLS
    #endif /* GNT_SLIDER_H */
    --- a/gntstyle.h Sun Feb 02 02:27:03 2014 +0530
    +++ b/gntstyle.h Sun Feb 02 03:34:37 2014 +0530
    @@ -38,113 +38,134 @@
    } GntStyle;
    /**
    - * Read configuration from a file.
    + * gnt_style_read_configure_file:
    + * @filename: The filename to read configuration from.
    *
    - * @filename: The filename to read configuration from.
    + * Read configuration from a file.
    */
    void gnt_style_read_configure_file(const char *filename);
    /**
    + * gnt_style_get:
    + * @style: The style.
    + *
    * Get the user-setting for a style.
    - * @style: The style.
    + *
    * Returns: The user-setting, or %NULL.
    */
    const char *gnt_style_get(GntStyle style);
    /**
    - * Get the value of a preference in ~/.gntrc.
    - *
    + * gnt_style_get_from_name:
    * @group: The name of the group in the keyfile. If %NULL, the prgname
    * will be used first, if available. Otherwise, "general" will be used.
    * @key: The key
    *
    + * Get the value of a preference in ~/.gntrc.
    + *
    * Returns: The value of the setting as a string, or %NULL
    *
    - * @since 2.0.0 (gnt), 2.1.0 (pidgin)
    + * Since: 2.0.0 (gnt), 2.1.0 (pidgin)
    */
    char *gnt_style_get_from_name(const char *group, const char *key);
    /**
    - * Get the value of a preference in ~/.gntrc.
    - *
    + * gnt_style_get_string_list:
    * @group: The name of the group in the keyfile. If %NULL, the prgname
    * will be used first, if available. Otherwise, "general" will be used.
    * @key: The key
    * @length: Return location for the number of strings returned, or NULL
    *
    + * Get the value of a preference in ~/.gntrc.
    + *
    * Returns: NULL terminated string array. The array should be freed with g_strfreev().
    *
    - * @since 2.4.0
    + * Since: 2.4.0
    */
    char **gnt_style_get_string_list(const char *group, const char *key, gsize *length);
    /**
    - * Get the value of a color pair in ~/.gntrc.
    - *
    + * gnt_style_get_color:
    * @group: The name of the group in the keyfile. If %NULL, the prgname
    * will be used first, if available. Otherwise, "general" will be used.
    * @key: The key
    *
    + * Get the value of a color pair in ~/.gntrc.
    + *
    * Returns: The value of the color as an int, or 0 on error.
    *
    - * @since 2.4.0
    + * Since: 2.4.0
    */
    int gnt_style_get_color(char *group, char *key);
    /**
    + * gnt_style_parse_bool:
    + * @value: The value of the boolean setting as a string
    + *
    * Parse a boolean preference. For example, if 'value' is "false" (ignoring case)
    * or "0", the return value will be %FALSE, otherwise %TRUE.
    *
    - * @value: The value of the boolean setting as a string
    * Returns: The boolean value
    *
    - * @since 2.0.0 (gnt), 2.1.0 (pidgin)
    + * Since: 2.0.0 (gnt), 2.1.0 (pidgin)
    */
    gboolean gnt_style_parse_bool(const char *value);
    /**
    - * Get the boolean value for a user-setting.
    - *
    + * gnt_style_get_bool:
    * @style: The style.
    * @def: The default value (i.e, the value if the user didn't define
    * any value)
    *
    + * Get the boolean value for a user-setting.
    + *
    * Returns: The value of the setting.
    */
    gboolean gnt_style_get_bool(GntStyle style, gboolean def);
    /**
    + * gnt_styles_get_keyremaps:
    + *
    * @internal
    */
    void gnt_styles_get_keyremaps(GType type, GHashTable *hash);
    /**
    + * gnt_style_read_actions:
    + *
    * @internal
    */
    void gnt_style_read_actions(GType type, GntBindableClass *klass);
    /**
    - * Read menu-accels from ~/.gntrc
    - *
    + * gnt_style_read_menu_accels:
    * @name: The name of the window.
    * @table: The hastable to store the accel information.
    *
    + * Read menu-accels from ~/.gntrc
    + *
    * Returns: %TRUE if some accels were read, %FALSE otherwise.
    */
    gboolean gnt_style_read_menu_accels(const char *name, GHashTable *table);
    /**
    + * gnt_style_read_workspaces:
    + *
    * @internal
    * Read workspace information.
    */
    void gnt_style_read_workspaces(GntWM *wm);
    /**
    + * gnt_init_styles:
    + *
    * Initialize style settings.
    */
    void gnt_init_styles(void);
    /**
    + * gnt_uninit_styles:
    + *
    * Uninitialize style settings.
    */
    void gnt_uninit_styles(void);
    --- a/gnttextview.h Sun Feb 02 02:27:03 2014 +0530
    +++ b/gnttextview.h Sun Feb 02 03:34:37 2014 +0530
    @@ -88,11 +88,15 @@
    G_BEGIN_DECLS
    /**
    + * gnt_text_view_get_gtype:
    + *
    * Returns: GType for GntTextView.
    */
    GType gnt_text_view_get_gtype(void);
    /**
    + * gnt_text_view_new:
    + *
    * Create a new textview.
    *
    * Returns: The newly created textview.
    @@ -100,96 +104,111 @@
    GntWidget * gnt_text_view_new(void);
    /**
    - * Scroll the textview.
    + * gnt_text_view_scroll:
    * @view: The textview to scroll.
    * @scroll: scroll > 0 means scroll up, < 0 means scroll down, == 0 means scroll to the end.
    + *
    + * Scroll the textview.
    */
    void gnt_text_view_scroll(GntTextView *view, int scroll);
    /**
    - * Append new text in a textview.
    - *
    + * gnt_text_view_append_text_with_flags:
    * @view: The textview.
    * @text: The text to append to the textview.
    * @flags: The text-flags to apply to the new text.
    + *
    + * Append new text in a textview.
    */
    void gnt_text_view_append_text_with_flags(GntTextView *view, const char *text, GntTextFormatFlags flags);
    /**
    - * Append text in the textview, with some identifier (tag) for the added text.
    - *
    + * gnt_text_view_append_text_with_tag:
    * @view: The textview.
    * @text: The text to append.
    * @flags: The text-flags to apply to the new text.
    - * @tag: The tag for the appended text, so it can be changed later (@see gnt_text_view_tag_change)
    + * @tag: The tag for the appended text, so it can be changed later (see gnt_text_view_tag_change())
    + *
    + * Append text in the textview, with some identifier (tag) for the added text.
    */
    void gnt_text_view_append_text_with_tag(GntTextView *view, const char *text, GntTextFormatFlags flags, const char *tag);
    /**
    + * gnt_text_view_next_line:
    + * @view: The textview.
    + *
    * Move the cursor to the beginning of the next line and resets text-attributes.
    * It first completes the current line with the current text-attributes.
    - *
    - * @view: The textview.
    */
    void gnt_text_view_next_line(GntTextView *view);
    /**
    - * Convert GNT-text formats to ncurses-text attributes.
    + * gnt_text_format_flag_to_chtype:
    + * @flags: The GNT text format.
    *
    - * @flags: The GNT text format.
    + * Convert GNT-text formats to ncurses-text attributes.
    *
    * Returns: Nucrses text attribute.
    */
    chtype gnt_text_format_flag_to_chtype(GntTextFormatFlags flags);
    /**
    - * Clear the contents of the textview.
    + * gnt_text_view_clear:
    + * @view: The textview.
    *
    - * @view: The textview.
    + * Clear the contents of the textview.
    */
    void gnt_text_view_clear(GntTextView *view);
    /**
    - * The number of lines below the bottom-most visible line.
    + * gnt_text_view_get_lines_below:
    + * @view: The textview.
    *
    - * @view: The textview.
    + * The number of lines below the bottom-most visible line.
    *
    * Returns: Number of lines below the bottom-most visible line.
    */
    int gnt_text_view_get_lines_below(GntTextView *view);
    /**
    - * The number of lines above the topmost visible line.
    + * gnt_text_view_get_lines_above:
    + * @view: The textview.
    *
    - * @view: The textview.
    + * The number of lines above the topmost visible line.
    *
    * Returns: Number of lines above the topmost visible line.
    */
    int gnt_text_view_get_lines_above(GntTextView *view);
    /**
    - * Change the text of a tag.
    - *
    + * gnt_text_view_tag_change:
    * @view: The textview.
    * @name: The name of the tag.
    * @text: The new text for the text. If 'text' is %NULL, the tag is removed.
    * @all: %TRUE if all of the instancess of the tag should be changed, %FALSE if
    * only the first instance should be changed.
    *
    + * Change the text of a tag.
    + *
    * Returns: The number of instances changed.
    */
    int gnt_text_view_tag_change(GntTextView *view, const char *name, const char *text, gboolean all);
    /**
    + * gnt_text_view_attach_scroll_widget:
    + * @view: The textview.
    + * @widget: The trigger widget.
    + *
    * Setup hooks so that pressing up/down/page-up/page-down keys when 'widget' is
    * in focus scrolls the textview.
    - *
    - * @view: The textview.
    - * @widget: The trigger widget.
    */
    void gnt_text_view_attach_scroll_widget(GntTextView *view, GntWidget *widget);
    /**
    + * gnt_text_view_attach_pager_widget:
    + * @view: The textview.
    + * @pager: The widget to trigger the PAGER.
    + *
    * Setup appropriate hooks so that pressing some keys when the 'pager' widget
    * is in focus triggers the PAGER to popup with the contents of the textview
    * in it.
    @@ -197,18 +216,19 @@
    * The default key-combination to trigger the pager is a-v, and the default
    * PAGER application is $PAGER. Both can be changed in ~/.gntrc like this:
    *
    - * @code
    + * <programlisting>
    * [pager]
    * key = a-v
    * path = /path/to/pager
    - * @endcode
    - *
    - * @view: The textview.
    - * @pager: The widget to trigger the PAGER.
    + * </programlisting>
    */
    void gnt_text_view_attach_pager_widget(GntTextView *view, GntWidget *pager);
    /**
    + * gnt_text_view_attach_editor_widget:
    + * @view: The textview.
    + * @widget: The widget to trigger the EDITOR.
    + *
    * Setup appropriate hooks so that pressing some keys when 'widget'
    * is in focus triggers the EDITOR to popup with the contents of the textview
    * in it.
    @@ -216,24 +236,22 @@
    * The default key-combination to trigger the pager is a-e, and the default
    * EDITOR application is $EDITOR. Both can be changed in ~/.gntrc like this:
    *
    - * @code
    + * <programlisting>
    * [editor]
    * key = a-e
    * path = /path/to/editor
    - * @endcode
    - *
    - * @view: The textview.
    - * @widget: The widget to trigger the EDITOR.
    + * </programlisting>
    */
    void gnt_text_view_attach_editor_widget(GntTextView *view, GntWidget *widget);
    /**
    - * Set a GntTextViewFlag for the textview widget.
    - *
    + * gnt_text_view_set_flag:
    * @view: The textview widget
    * @flag: The flag to set
    *
    - * @since 2.0.0 (gnt), 2.1.0 (pidgin)
    + * Set a GntTextViewFlag for the textview widget.
    + *
    + * Since: 2.0.0 (gnt), 2.1.0 (pidgin)
    */
    void gnt_text_view_set_flag(GntTextView *view, GntTextViewFlag flag);
    --- a/gnttree.h Sun Feb 02 02:27:03 2014 +0530
    +++ b/gnttree.h Sun Feb 02 03:34:37 2014 +0530
    @@ -102,11 +102,15 @@
    G_BEGIN_DECLS
    /**
    + * gnt_tree_get_gtype:
    + *
    * Returns: The GType for GntTree
    */
    GType gnt_tree_get_gtype(void);
    /**
    + * gnt_tree_new:
    + *
    * Create a tree with one column.
    *
    * Returns: The newly created tree
    @@ -116,508 +120,562 @@
    GntWidget * gnt_tree_new(void);
    /**
    - * Create a tree with a specified number of columns.
    - *
    + * gnt_tree_new_with_columns:
    * @columns: Number of columns
    *
    - * Returns: The newly created tree
    + * Create a tree with a specified number of columns.
    *
    * @see gnt_tree_new
    + *
    + * Returns: The newly created tree
    */
    GntWidget * gnt_tree_new_with_columns(int columns);
    /**
    - * The number of rows the tree should display at a time.
    - *
    + * gnt_tree_set_visible_rows:
    * @tree: The tree
    * @rows: The number of rows
    + *
    + * The number of rows the tree should display at a time.
    */
    void gnt_tree_set_visible_rows(GntTree *tree, int rows);
    /**
    - * Get the number visible rows.
    + * gnt_tree_get_visible_rows:
    + * @tree: The tree
    *
    - * @tree: The tree
    + * Get the number visible rows.
    *
    * Returns: The number of visible rows
    */
    int gnt_tree_get_visible_rows(GntTree *tree);
    /**
    - * Scroll the contents of the tree.
    - *
    + * gnt_tree_scroll:
    * @tree: The tree
    * @count: If positive, the tree will be scrolled down by count rows,
    * otherwise, it will be scrolled up by count rows.
    + *
    + * Scroll the contents of the tree.
    */
    void gnt_tree_scroll(GntTree *tree, int count);
    /**
    - * Insert a row in the tree.
    - *
    + * gnt_tree_add_row_after:
    * @tree: The tree
    * @key: The key for the row
    * @row: The row to insert
    * @parent: The key for the parent row
    * @bigbro: The key for the row to insert the new row after.
    *
    - * Returns: The inserted row
    + * Insert a row in the tree.
    *
    * @see gnt_tree_create_row
    * @see gnt_tree_add_row_last
    * @see gnt_tree_add_choice
    + *
    + * Returns: The inserted row
    */
    GntTreeRow * gnt_tree_add_row_after(GntTree *tree, void *key, GntTreeRow *row, void *parent, void *bigbro);
    /**
    - * Insert a row at the end of the tree.
    - *
    + * gnt_tree_add_row_last:
    * @tree: The tree
    * @key: The key for the row
    * @row: The row to insert
    * @parent: The key for the parent row
    *
    - * Returns: The inserted row
    + * Insert a row at the end of the tree.
    *
    * @see gnt_tree_create_row
    * @see gnt_tree_add_row_after
    * @see gnt_tree_add_choice
    + *
    + * Returns: The inserted row
    */
    GntTreeRow * gnt_tree_add_row_last(GntTree *tree, void *key, GntTreeRow *row, void *parent);
    /**
    - * Get the key for the selected row.
    + * gnt_tree_get_selection_data:
    + * @tree: The tree
    *
    - * @tree: The tree
    + * Get the key for the selected row.
    *
    * Returns: The key for the selected row
    */
    gpointer gnt_tree_get_selection_data(GntTree *tree);
    /**
    - * Get the text displayed for the selected row.
    - *
    + * gnt_tree_get_selection_text:
    * @tree: The tree
    *
    - * Returns: The text, which needs to be freed by the caller
    + * Get the text displayed for the selected row.
    + *
    * @see gnt_tree_get_row_text_list
    * @see gnt_tree_get_selection_text_list
    + *
    + * Returns: The text, which needs to be freed by the caller
    */
    char * gnt_tree_get_selection_text(GntTree *tree);
    /**
    - * Get a list of text for a row.
    - *
    + * gnt_tree_get_row_text_list:
    * @tree: The tree
    * @key: A key corresponding to the row in question. If key
    * is %NULL, the text list for the selected row will
    * be returned.
    *
    + * Get a list of text for a row.
    + *
    + * @see gnt_tree_get_selection_text_list
    + * @see gnt_tree_get_selection_text
    + *
    * Returns: A list of texts of a row. The list and its data should be
    * freed by the caller. The caller should make sure that if
    * any column of the tree contains binary data, it's not freed.
    - * @see gnt_tree_get_selection_text_list
    - * @see gnt_tree_get_selection_text
    */
    GList * gnt_tree_get_row_text_list(GntTree *tree, gpointer key);
    /**
    - * Get the key of a row.
    - *
    + * gnt_tree_row_get_key:
    * @tree: The tree
    * @row: The GntTreeRow object
    *
    + * Get the key of a row.
    + *
    * Returns: The key of the row.
    - * @since 2.8.0 (gnt), 2.7.2 (pidgin)
    + *
    + * Since: 2.8.0 (gnt), 2.7.2 (pidgin)
    */
    gpointer gnt_tree_row_get_key(GntTree *tree, GntTreeRow *row);
    /**
    - * Get the next row.
    - *
    + * gnt_tree_row_get_next:
    * @tree: The tree
    * @row: The GntTreeRow object
    *
    + * Get the next row.
    + *
    * Returns: The next row.
    - * @since 2.8.0 (gnt), 2.7.2 (pidgin)
    + *
    + * Since: 2.8.0 (gnt), 2.7.2 (pidgin)
    */
    GntTreeRow * gnt_tree_row_get_next(GntTree *tree, GntTreeRow *row);
    /**
    - * Get the previous row.
    - *
    + * gnt_tree_row_get_prev:
    * @tree: The tree
    * @row: The GntTreeRow object
    *
    + * Get the previous row.
    + *
    * Returns: The previous row.
    - * @since 2.8.0 (gnt), 2.7.2 (pidgin)
    + *
    + * Since: 2.8.0 (gnt), 2.7.2 (pidgin)
    */
    GntTreeRow * gnt_tree_row_get_prev(GntTree *tree, GntTreeRow *row);
    /**
    - * Get the child row.
    - *
    + * gnt_tree_row_get_child:
    * @tree: The tree
    * @row: The GntTreeRow object
    *
    + * Get the child row.
    + *
    * Returns: The child row.
    - * @since 2.8.0 (gnt), 2.7.2 (pidgin)
    + *
    + * Since: 2.8.0 (gnt), 2.7.2 (pidgin)
    */
    GntTreeRow * gnt_tree_row_get_child(GntTree *tree, GntTreeRow *row);
    /**
    - * Get the parent row.
    - *
    + * gnt_tree_row_get_parent:
    * @tree: The tree
    * @row: The GntTreeRow object
    *
    + * Get the parent row.
    + *
    * Returns: The parent row.
    - * @since 2.8.0 (gnt), 2.7.2 (pidgin)
    + *
    + * Since: 2.8.0 (gnt), 2.7.2 (pidgin)
    */
    GntTreeRow * gnt_tree_row_get_parent(GntTree *tree, GntTreeRow *row);
    /**
    + * gnt_tree_get_selection_text_list:
    + * @tree: The tree
    + *
    * Get a list of text of the current row.
    *
    - * @tree: The tree
    + * @see gnt_tree_get_row_text_list
    + * @see gnt_tree_get_selection_text
    *
    * Returns: A list of texts of the currently selected row. The list
    * and its data should be freed by the caller. The caller
    * should make sure that if any column of the tree contains
    * binary data, it's not freed.
    - * @see gnt_tree_get_row_text_list
    - * @see gnt_tree_get_selection_text
    */
    GList * gnt_tree_get_selection_text_list(GntTree *tree);
    /**
    - * Returns the list of rows in the tree.
    + * gnt_tree_get_rows:
    + * @tree: The tree
    *
    - * @tree: The tree
    + * Returns the list of rows in the tree.
    *
    * Returns: The list of the rows. The list should not be modified by the caller.
    */
    GList *gnt_tree_get_rows(GntTree *tree);
    /**
    - * Remove a row from the tree.
    - *
    + * gnt_tree_remove:
    * @tree: The tree
    * @key: The key for the row to remove
    + *
    + * Remove a row from the tree.
    */
    void gnt_tree_remove(GntTree *tree, gpointer key);
    /**
    - * Remove all the item from the tree.
    + * gnt_tree_remove_all:
    + * @tree: The tree
    *
    - * @tree: The tree
    + * Remove all the item from the tree.
    */
    void gnt_tree_remove_all(GntTree *tree);
    /**
    - * Get the visible line number of the selected row.
    + * gnt_tree_get_selection_visible_line:
    + * @tree: The tree
    *
    - * @tree: The tree
    + * Get the visible line number of the selected row.
    *
    * Returns: The line number of the currently selected row
    */
    int gnt_tree_get_selection_visible_line(GntTree *tree);
    /**
    - * Change the text of a column in a row.
    - *
    + * gnt_tree_change_text:
    * @tree: The tree
    * @key: The key for the row
    * @colno: The index of the column
    * @text: The new text
    + *
    + * Change the text of a column in a row.
    */
    void gnt_tree_change_text(GntTree *tree, gpointer key, int colno, const char *text);
    /**
    - * Add a checkable item in the tree.
    - *
    + * gnt_tree_add_choice:
    * @tree: The tree
    * @key: The key for the row
    * @row: The row to add
    * @parent: The parent of the row, or %NULL
    * @bigbro: The row to insert after, or %NULL
    *
    - * Returns: The row inserted.
    + * Add a checkable item in the tree.
    *
    * @see gnt_tree_create_row
    * @see gnt_tree_create_row_from_list
    * @see gnt_tree_add_row_last
    * @see gnt_tree_add_row_after
    + *
    + * Returns: The row inserted.
    */
    GntTreeRow * gnt_tree_add_choice(GntTree *tree, void *key, GntTreeRow *row, void *parent, void *bigbro);
    /**
    - * Set whether a checkable item is checked or not.
    - *
    + * gnt_tree_set_choice:
    * @tree: The tree
    * @key: The key for the row
    * @set: %TRUE if the item should be checked, %FALSE if not
    + *
    + * Set whether a checkable item is checked or not.
    */
    void gnt_tree_set_choice(GntTree *tree, void *key, gboolean set);
    /**
    - * Return whether a row is selected or not, where the row is a checkable item.
    - *
    + * gnt_tree_get_choice:
    * @tree: The tree
    * @key: The key for the row
    *
    + * Return whether a row is selected or not, where the row is a checkable item.
    + *
    * Returns: %TRUE if the row is checked, %FALSE otherwise.
    */
    gboolean gnt_tree_get_choice(GntTree *tree, void *key);
    /**
    - * Set flags for the text in a row in the tree.
    - *
    + * gnt_tree_set_row_flags:
    * @tree: The tree
    * @key: The key for the row
    * @flags: The flags to set
    + *
    + * Set flags for the text in a row in the tree.
    */
    void gnt_tree_set_row_flags(GntTree *tree, void *key, GntTextFormatFlags flags);
    /**
    - * Set color for the text in a row in the tree.
    - *
    + * gnt_tree_set_row_color:
    * @tree: The tree
    * @key: The key for the row
    * @color: The color
    - * @since 2.4.0
    + *
    + * Set color for the text in a row in the tree.
    + *
    + * Since: 2.4.0
    */
    void gnt_tree_set_row_color(GntTree *tree, void *key, int color);
    /**
    - * Select a row.
    - *
    + * gnt_tree_set_selected:
    * @tree: The tree
    * @key: The key of the row to select
    + *
    + * Select a row.
    */
    void gnt_tree_set_selected(GntTree *tree , void *key);
    /**
    - * Create a row to insert in the tree.
    - *
    + * gnt_tree_create_row:
    * @tree: The tree
    * @...: A string for each column in the tree
    *
    - * Returns: The row
    + * Create a row to insert in the tree.
    *
    * @see gnt_tree_create_row_from_list
    * @see gnt_tree_add_row_after
    * @see gnt_tree_add_row_last
    * @see gnt_tree_add_choice
    + *
    + * Returns: The row
    */
    GntTreeRow * gnt_tree_create_row(GntTree *tree, ...);
    /**
    - * Create a row from a list of text.
    - *
    + * gnt_tree_create_row_from_list:
    * @tree: The tree
    * @list: The list containing the text for each column
    *
    - * Returns: The row
    + * Create a row from a list of text.
    *
    * @see gnt_tree_create_row
    * @see gnt_tree_add_row_after
    * @see gnt_tree_add_row_last
    * @see gnt_tree_add_choice
    + *
    + * Returns: The row
    */
    GntTreeRow * gnt_tree_create_row_from_list(GntTree *tree, GList *list);
    /**
    - * Set the width of a column in the tree.
    - *
    + * gnt_tree_set_col_width:
    * @tree: The tree
    * @col: The index of the column
    * @width: The width for the column
    *
    + * Set the width of a column in the tree.
    + *
    * @see gnt_tree_set_column_width_ratio
    * @see gnt_tree_set_column_resizable
    */
    void gnt_tree_set_col_width(GntTree *tree, int col, int width);
    /**
    - * Set the title for a column.
    - *
    + * gnt_tree_set_column_title:
    * @tree: The tree
    * @index: The index of the column
    * @title: The title for the column
    *
    + * Set the title for a column.
    + *
    * @see gnt_tree_set_column_titles
    * @see gnt_tree_set_show_title
    *
    - * @since 2.0.0 (gnt), 2.1.0 (pidgin)
    + * Since: 2.0.0 (gnt), 2.1.0 (pidgin)
    */
    void gnt_tree_set_column_title(GntTree *tree, int index, const char *title);
    /**
    - * Set the titles of the columns
    - *
    + * gnt_tree_set_column_titles:
    * @tree: The tree
    * @...: One title for each column in the tree
    *
    + * Set the titles of the columns
    + *
    * @see gnt_tree_set_column_title
    * @see gnt_tree_set_show_title
    */
    void gnt_tree_set_column_titles(GntTree *tree, ...);
    /**
    - * Set whether to display the title of the columns.
    - *
    + * gnt_tree_set_show_title:
    * @tree: The tree
    * @set: If %TRUE, the column titles are displayed
    *
    + * Set whether to display the title of the columns.
    + *
    * @see gnt_tree_set_column_title
    * @see gnt_tree_set_column_titles
    */
    void gnt_tree_set_show_title(GntTree *tree, gboolean set);
    /**
    - * Set the compare function for sorting the data.
    - *
    + * gnt_tree_set_compare_func:
    * @tree: The tree
    * @func: The comparison function, which is used to compare
    * the keys
    *
    + * Set the compare function for sorting the data.
    + *
    * @see gnt_tree_sort_row
    */
    void gnt_tree_set_compare_func(GntTree *tree, GCompareFunc func);
    /**
    - * Set whether a row, which has child rows, should be expanded.
    - *
    + * gnt_tree_set_expanded:
    * @tree: The tree
    * @key: The key of the row
    * @expanded: Whether to expand the child rows
    + *
    + * Set whether a row, which has child rows, should be expanded.
    */
    void gnt_tree_set_expanded(GntTree *tree, void *key, gboolean expanded);
    /**
    - * Set whether to show column separators.
    - *
    + * gnt_tree_set_show_separator:
    * @tree: The tree
    * @set: If %TRUE, the column separators are displayed
    + *
    + * Set whether to show column separators.
    */
    void gnt_tree_set_show_separator(GntTree *tree, gboolean set);
    /**
    - * Sort a row in the tree.
    - *
    + * gnt_tree_sort_row:
    * @tree: The tree
    * @row: The row to sort
    *
    + * Sort a row in the tree.
    + *
    * @see gnt_tree_set_compare_func
    */
    void gnt_tree_sort_row(GntTree *tree, void *row);
    /**
    - * Automatically adjust the width of the columns in the tree.
    + * gnt_tree_adjust_columns:
    + * @tree: The tree
    *
    - * @tree: The tree
    + * Automatically adjust the width of the columns in the tree.
    */
    void gnt_tree_adjust_columns(GntTree *tree);
    /**
    - * Set the hash functions to use to hash, compare and free the keys.
    - *
    + * gnt_tree_set_hash_fns:
    * @tree: The tree
    * @hash: The hashing function
    * @eq: The function to compare keys
    * @kd: The function to use to free the keys when a row is removed
    * from the tree
    + *
    + * Set the hash functions to use to hash, compare and free the keys.
    */
    void gnt_tree_set_hash_fns(GntTree *tree, gpointer hash, gpointer eq, gpointer kd);
    /**
    + * gnt_tree_set_column_visible:
    + * @tree: The tree
    + * @col: The index of the column
    + * @vis: If %FALSE, the column will not be displayed
    + *
    * Set whether a column is visible or not.
    * This can be useful when, for example, we want to store some data
    * which we don't want/need to display.
    - *
    - * @tree: The tree
    - * @col: The index of the column
    - * @vis: If %FALSE, the column will not be displayed
    */
    void gnt_tree_set_column_visible(GntTree *tree, int col, gboolean vis);
    /**
    - * Set whether a column can be resized to keep the same ratio when the
    - * tree is resized.
    - *
    + * gnt_tree_set_column_resizable:
    * @tree: The tree
    * @col: The index of the column
    * @res: If %FALSE, the column will not be resized when the
    * tree is resized
    *
    + * Set whether a column can be resized to keep the same ratio when the
    + * tree is resized.
    + *
    * @see gnt_tree_set_col_width
    * @see gnt_tree_set_column_width_ratio
    *
    - * @since 2.0.0 (gnt), 2.1.0 (pidgin)
    + * Since: 2.0.0 (gnt), 2.1.0 (pidgin)
    */
    void gnt_tree_set_column_resizable(GntTree *tree, int col, gboolean res);
    /**
    - * Set whether data in a column should be considered as binary data, and
    - * not as strings. A column containing binary data will be display empty text.
    - *
    + * gnt_tree_set_column_is_binary:
    * @tree: The tree
    * @col: The index of the column
    * @bin: %TRUE if the data for the column is binary
    + *
    + * Set whether data in a column should be considered as binary data, and
    + * not as strings. A column containing binary data will be display empty text.
    */
    void gnt_tree_set_column_is_binary(GntTree *tree, int col, gboolean bin);
    /**
    - * Set whether text in a column should be right-aligned.
    - *
    + * gnt_tree_set_column_is_right_aligned:
    * @tree: The tree
    * @col: The index of the column
    * @right: %TRUE if the text in the column should be right aligned
    *
    - * @since 2.0.0 (gnt), 2.1.0 (pidgin)
    + * Set whether text in a column should be right-aligned.
    + *
    + * Since: 2.0.0 (gnt), 2.1.0 (pidgin)
    */
    void gnt_tree_set_column_is_right_aligned(GntTree *tree, int col, gboolean right);
    /**
    - * Set column widths to use when calculating column widths after a tree
    - * is resized.
    - *
    + * gnt_tree_set_column_width_ratio:
    * @tree: The tree
    * @cols: Array of widths. The width must have the same number
    * of entries as the number of columns in the tree, or
    * end with a negative value for a column-width.
    *
    + * Set column widths to use when calculating column widths after a tree
    + * is resized.
    + *
    * @see gnt_tree_set_col_width
    * @see gnt_tree_set_column_resizable
    *
    - * @since 2.0.0 (gnt), 2.1.0 (pidgin)
    + * Since: 2.0.0 (gnt), 2.1.0 (pidgin)
    */
    void gnt_tree_set_column_width_ratio(GntTree *tree, int cols[]);
    /**
    - * Set the column to use for typeahead searching.
    - *
    + * gnt_tree_set_search_column:
    * @tree: The tree
    * @col: The index of the column
    *
    - * @since 2.0.0 (gnt), 2.1.0 (pidgin)
    + * Set the column to use for typeahead searching.
    + *
    + * Since: 2.0.0 (gnt), 2.1.0 (pidgin)
    */
    void gnt_tree_set_search_column(GntTree *tree, int col);
    /**
    + * gnt_tree_is_searching:
    + * @tree: The tree
    + *
    * Check whether the user is currently in the middle of a search.
    *
    - * @tree: The tree
    * Returns: %TRUE if the user is searching, %FALSE otherwise.
    *
    - * @since 2.0.0 (gnt), 2.1.0 (pidgin)
    + * Since: 2.0.0 (gnt), 2.1.0 (pidgin)
    */
    gboolean gnt_tree_is_searching(GntTree *tree);
    /**
    - * Set a custom search function.
    - *
    + * gnt_tree_set_search_function:
    * @tree: The tree
    * @func: The custom search function. The search function is
    * sent the tree itself, the key of a row, the search
    @@ -625,19 +683,23 @@
    * If the function returns %TRUE, the row is dislayed,
    * otherwise it's not.
    *
    - * @since 2.0.0 (gnt), 2.1.0 (pidgin)
    + * Set a custom search function.
    + *
    + * Since: 2.0.0 (gnt), 2.1.0 (pidgin)
    */
    void gnt_tree_set_search_function(GntTree *tree,
    gboolean (*func)(GntTree *tree, gpointer key, const char *search, const char *current));
    /**
    - * Get the parent key for a row.
    - *
    + * gnt_tree_get_parent_key:
    * @tree: The tree
    * @key: The key for the row.
    *
    + * Get the parent key for a row.
    + *
    * Returns: The key of the parent row.
    - * @since 2.4.0
    + *
    + * Since: 2.4.0
    */
    gpointer gnt_tree_get_parent_key(GntTree *tree, gpointer key);
    --- a/gntutils.h Sun Feb 02 02:27:03 2014 +0530
    +++ b/gntutils.h Sun Feb 02 03:34:37 2014 +0530
    @@ -33,53 +33,56 @@
    typedef gpointer (*GDupFunc)(gconstpointer data);
    /**
    - * Compute the width and height required to view the text on the screen.
    - *
    + * gnt_util_get_text_bound:
    * @text: The text to be displayed.
    * @width: The width required is set here, if not %NULL.
    * @height: The height required is set here, if not %NULL.
    + *
    + * Compute the width and height required to view the text on the screen.
    */
    void gnt_util_get_text_bound(const char *text, int *width, int *height);
    /* excluding *end */
    /**
    - * Get the onscreen width of a string, or a substring.
    - *
    + * gnt_util_onscreen_width:
    * @start: The beginning of the string.
    * @end: The end of the string. The width returned is the width
    * upto (but not including) end. If end is NULL, then start
    * is considered as a %NULL-terminated string.
    *
    + * Get the onscreen width of a string, or a substring.
    + *
    * Returns: The on-screen width of the string.
    */
    int gnt_util_onscreen_width(const char *start, const char *end);
    /**
    - * Computes and returns the string after a specific number of onscreen characters.
    - *
    + * gnt_util_onscreen_width_to_pointer:
    * @str: The string.
    * @len: The length to consider. If non-positive, the entire screenlength is used.
    * @w: The actual width of the string upto the returned offset, if not %NULL.
    *
    + * Computes and returns the string after a specific number of onscreen characters.
    + *
    * Returns: The string after len offset.
    */
    const char *gnt_util_onscreen_width_to_pointer(const char *str, int len, int *w);
    /**
    - * Inserts newlines in 'string' where necessary so that its onscreen width is
    - * no more than 'maxw'.
    - *
    + * gnt_util_onscreen_fit_string:
    * @string: The string.
    * @maxw: The width that the string should fit into. If maxw is <= 0,
    * then the available maximum width is used.
    *
    + * Inserts newlines in 'string' where necessary so that its onscreen width is
    + * no more than 'maxw'.
    + *
    * Returns: A newly allocated string that needs to be freed by the caller.
    */
    char * gnt_util_onscreen_fit_string(const char *string, int maxw);
    /**
    - * Duplicate the contents of a hastable.
    - *
    + * g_hash_table_duplicate:
    * @src: The source hashtable.
    * @hash: The hash-function to use.
    * @equal: The hash-equal function to use.
    @@ -88,36 +91,38 @@
    * @key_dup: The function to use to duplicate the key.
    * @value_dup: The function to use to duplicate the value.
    *
    + * Duplicate the contents of a hastable.
    + *
    * Returns: The new hashtable.
    */
    GHashTable * g_hash_table_duplicate(GHashTable *src, GHashFunc hash, GEqualFunc equal, GDestroyNotify key_d, GDestroyNotify value_d, GDupFunc key_dup, GDupFunc value_dup);
    /**
    + * gnt_boolean_handled_accumulator:
    + *
    * To be used with g_signal_new. Look in the key_pressed signal-definition in
    * gntwidget.c for usage.
    - *
    - * @ihint: NA
    - * Returns:_accu: NA
    - * @handler_return: NA
    - * @dummy: NA
    - *
    - * Returns: NA
    */
    gboolean gnt_boolean_handled_accumulator(GSignalInvocationHint *ihint, GValue *return_accu, const GValue *handler_return, gpointer dummy);
    /**
    - * Get a helpful display about the bindings of a widget.
    + * gnt_widget_bindings_view:
    + * @widget: The widget to get bindings for.
    *
    - * @widget: The widget to get bindings for.
    + * Get a helpful display about the bindings of a widget.
    *
    * Returns: Returns a GntTree populated with "key" -> "binding" for the widget.
    */
    GntWidget * gnt_widget_bindings_view(GntWidget *widget);
    /**
    + * gnt_util_parse_widgets:
    + * @string: The XML string.
    + * @num: The number of widgets to return, followed by 'num' GntWidget **
    + *
    * Parse widgets from an XML description. For example,
    *
    - * @code
    + * <programlisting>
    * GntWidget *win, *button;
    * gnt_util_parse_widgets("\
    * <vwindow id='0' fill='0' align='2'> \
    @@ -125,33 +130,33 @@
    * <button id='1'>OK</button> \
    * </vwindow>",
    * 2, &win, &button);
    - * @endcode
    - *
    - * @string: The XML string.
    - * @num: The number of widgets to return, followed by 'num' GntWidget **
    + * </programlisting>
    */
    void gnt_util_parse_widgets(const char *string, int num, ...);
    /**
    + * gnt_util_parse_xhtml_to_textview:
    + * @string: The XHTML string
    + * @tv: The GntTextView
    + *
    * Parse an XHTML string and add it in a GntTextView with
    * appropriate text flags.
    *
    - * @string: The XHTML string
    - * @tv: The GntTextView
    * Returns: %TRUE if the string was added to the textview properly, %FALSE otherwise.
    *
    - * @since 2.2.0
    + * Since: 2.2.0
    */
    gboolean gnt_util_parse_xhtml_to_textview(const char *string, GntTextView *tv);
    /**
    - * Make some keypress activate a button when some key is pressed with 'wid' in focus.
    - *
    + * gnt_util_set_trigger_widget:
    * @widget: The widget
    * @key: The key to trigger the button
    * @button: The button to trigger
    *
    - * @since 2.0.0 (gnt), 2.1.0 (pidgin)
    + * Make some keypress activate a button when some key is pressed with 'wid' in focus.
    + *
    + * Since: 2.0.0 (gnt), 2.1.0 (pidgin)
    */
    void gnt_util_set_trigger_widget(GntWidget *widget, const char *key, GntWidget *button);
    --- a/gntwidget.h Sun Feb 02 02:27:03 2014 +0530
    +++ b/gntwidget.h Sun Feb 02 03:34:37 2014 +0530
    @@ -140,173 +140,209 @@
    G_BEGIN_DECLS
    /**
    + * gnt_widget_get_gtype:
    + *
    * Returns: GType for GntWidget.
    */
    GType gnt_widget_get_gtype(void);
    /**
    + * gnt_widget_destroy:
    + * @widget: The widget to destroy.
    + *
    * Destroy a widget.
    - * @widget: The widget to destroy.
    */
    void gnt_widget_destroy(GntWidget *widget);
    /**
    + * gnt_widget_show:
    + * @widget: The widget to show.
    + *
    * Show a widget. This should only be used for toplevel widgets. For the rest
    * of the widgets, use #gnt_widget_draw instead.
    - *
    - * @widget: The widget to show.
    */
    void gnt_widget_show(GntWidget *widget);
    /**
    + * gnt_widget_draw:
    + * @widget: The widget to draw.
    + *
    * Draw a widget.
    - * @widget: The widget to draw.
    */
    void gnt_widget_draw(GntWidget *widget);
    /**
    + * gnt_widget_expose:
    + *
    * @internal
    * Expose part of a widget.
    */
    void gnt_widget_expose(GntWidget *widget, int x, int y, int width, int height);
    /**
    + * gnt_widget_hide:
    + * @widget: The widget to hide.
    + *
    * Hide a widget.
    - * @widget: The widget to hide.
    */
    void gnt_widget_hide(GntWidget *widget);
    /**
    - * Get the position of a widget.
    - *
    + * gnt_widget_get_position:
    * @widget: The widget.
    * @x: Location to store the x-coordinate of the widget.
    * @y: Location to store the y-coordinate of the widget.
    + *
    + * Get the position of a widget.
    */
    void gnt_widget_get_position(GntWidget *widget, int *x, int *y);
    /**
    - * Set the position of a widget.
    + * gnt_widget_set_position:
    * @widget: The widget to reposition.
    * @x: The x-coordinate of the widget.
    * @y: The x-coordinate of the widget.
    + *
    + * Set the position of a widget.
    */
    void gnt_widget_set_position(GntWidget *widget, int x, int y);
    /**
    + * gnt_widget_size_request:
    + * @widget: The widget.
    + *
    * Request a widget to calculate its desired size.
    - * @widget: The widget.
    */
    void gnt_widget_size_request(GntWidget *widget);
    /**
    - * Get the size of a widget.
    + * gnt_widget_get_size:
    * @widget: The widget.
    * @width: Location to store the width of the widget.
    * @height: Location to store the height of the widget.
    + *
    + * Get the size of a widget.
    */
    void gnt_widget_get_size(GntWidget *widget, int *width, int *height);
    /**
    - * Set the size of a widget.
    - *
    + * gnt_widget_set_size:
    * @widget: The widget to resize.
    * @width: The width of the widget.
    * @height: The height of the widget.
    *
    + * Set the size of a widget.
    + *
    * Returns: If the widget was resized to the new size.
    */
    gboolean gnt_widget_set_size(GntWidget *widget, int width, int height);
    /**
    - * Confirm a requested a size for a widget.
    - *
    + * gnt_widget_confirm_size:
    * @widget: The widget.
    * @width: The requested width.
    * @height: The requested height.
    *
    + * Confirm a requested a size for a widget.
    + *
    * Returns: %TRUE if the new size was confirmed, %FALSE otherwise.
    */
    gboolean gnt_widget_confirm_size(GntWidget *widget, int width, int height);
    /**
    - * Trigger the key-press callbacks for a widget.
    - *
    + * gnt_widget_key_pressed:
    * @widget: The widget.
    * @keys: The keypress on the widget.
    *
    + * Trigger the key-press callbacks for a widget.
    + *
    * Returns: %TRUE if the key-press was handled, %FALSE otherwise.
    */
    gboolean gnt_widget_key_pressed(GntWidget *widget, const char *keys);
    /**
    - * Trigger the 'click' callback of a widget.
    - *
    + * gnt_widget_clicked:
    * @widget: The widget.
    * @event: The mouseevent.
    * @x: The x-coordinate of the mouse.
    * @y: The y-coordinate of the mouse.
    *
    + * Trigger the 'click' callback of a widget.
    + *
    * Returns: %TRUE if the event was handled, %FALSE otherwise.
    */
    gboolean gnt_widget_clicked(GntWidget *widget, GntMouseEvent event, int x, int y);
    /**
    - * Give or remove focus to a widget.
    + * gnt_widget_set_focus:
    * @widget: The widget.
    * @set: %TRUE of focus should be given to the widget, %FALSE if
    * focus should be removed.
    *
    + * Give or remove focus to a widget.
    + *
    * Returns: %TRUE if the focus has been changed, %FALSE otherwise.
    */
    gboolean gnt_widget_set_focus(GntWidget *widget, gboolean set);
    /**
    + * gnt_widget_activate:
    + * @widget: The widget to activate.
    + *
    * Activate a widget. This only applies to widgets that can be activated (eg. GntButton)
    - * @widget: The widget to activate.
    */
    void gnt_widget_activate(GntWidget *widget);
    /**
    - * Set the name of a widget.
    + * gnt_widget_set_name:
    * @widget: The widget.
    * @name: A new name for the widget.
    + *
    + * Set the name of a widget.
    */
    void gnt_widget_set_name(GntWidget *widget, const char *name);
    /**
    + * gnt_widget_get_name:
    + * @widget: The widget.
    + *
    * Get the name of a widget.
    - * @widget: The widget.
    + *
    * Returns: The name of the widget.
    */
    const char *gnt_widget_get_name(GntWidget *widget);
    /**
    + * gnt_widget_queue_update:
    + *
    * @internal
    * Use #gnt_widget_draw instead.
    */
    void gnt_widget_queue_update(GntWidget *widget);
    /**
    - * Set whether a widget can take focus or not.
    - *
    + * gnt_widget_set_take_focus:
    * @widget: The widget.
    * @set: %TRUE if the widget can take focus.
    + *
    + * Set whether a widget can take focus or not.
    */
    void gnt_widget_set_take_focus(GntWidget *widget, gboolean set);
    /**
    - * Set the visibility of a widget.
    - *
    + * gnt_widget_set_visible:
    * @widget: The widget.
    * @set: Whether the widget is visible or not.
    + *
    + * Set the visibility of a widget.
    */
    void gnt_widget_set_visible(GntWidget *widget, gboolean set);
    /**
    - * Check whether the widget has shadows.
    + * gnt_widget_has_shadow:
    + * @widget: The widget.
    *
    - * @widget: The widget.
    + * Check whether the widget has shadows.
    *
    * Returns: %TRUE if the widget has shadows. This checks both the user-setting
    * and whether the widget can have shadows at all.
    --- a/gntwindow.h Sun Feb 02 02:27:03 2014 +0530
    +++ b/gntwindow.h Sun Feb 02 03:34:37 2014 +0530
    @@ -74,6 +74,8 @@
    G_BEGIN_DECLS
    /**
    + * gnt_window_get_gtype:
    + *
    * Returns: GType for GntWindow.
    */
    GType gnt_window_get_gtype(void);
    @@ -82,6 +84,8 @@
    #define gnt_hwindow_new(homo) gnt_window_box_new(homo, FALSE)
    /**
    + * gnt_window_new:
    + *
    * Create a new window.
    *
    * Returns: The newly created window.
    @@ -89,53 +93,58 @@
    GntWidget * gnt_window_new(void);
    /**
    - * Create a new window.
    - *
    + * gnt_window_box_new:
    * @homo: %TRUE if the widgets inside the window should have the same dimensions.
    * @vert: %TRUE if the widgets inside the window should be stacked vertically.
    *
    + * Create a new window.
    + *
    * Returns: The newly created window.
    */
    GntWidget * gnt_window_box_new(gboolean homo, gboolean vert);
    /**
    - * Set the menu for a window.
    - *
    + * gnt_window_set_menu:
    * @window: The window.
    * @menu: The menu for the window.
    + *
    + * Set the menu for a window.
    */
    void gnt_window_set_menu(GntWindow *window, GntMenu *menu);
    /**
    - * Return the id of a menuitem specified to a keystroke.
    - *
    + * gnt_window_get_accel_item:
    * @window: The window.
    * @key: The keystroke.
    *
    + * Return the id of a menuitem specified to a keystroke.
    + *
    * Returns: The id of the menuitem bound to the keystroke, or %NULL.
    *
    - * @since 2.3.0
    + * Since: 2.3.0
    */
    const char * gnt_window_get_accel_item(GntWindow *window, const char *key);
    /**
    - * Maximize a window, either horizontally or vertically, or both.
    - *
    + * gnt_window_set_maximize:
    * @window: The window to maximize.
    * @maximize: The maximization state of the window.
    *
    - * @since 2.3.0
    + * Maximize a window, either horizontally or vertically, or both.
    + *
    + * Since: 2.3.0
    */
    void gnt_window_set_maximize(GntWindow *window, GntWindowFlags maximize);
    /**
    - * Get the maximization state of a window.
    + * gnt_window_get_maximize:
    + * @window: The window.
    *
    - * @window: The window.
    + * Get the maximization state of a window.
    *
    * Returns: The maximization state of the window.
    *
    - * @since 2.3.0
    + * Since: 2.3.0
    */
    GntWindowFlags gnt_window_get_maximize(GntWindow *window);
    --- a/gntwm.h Sun Feb 02 02:27:03 2014 +0530
    +++ b/gntwm.h Sun Feb 02 03:34:37 2014 +0530
    @@ -68,6 +68,8 @@
    } GntPosition;
    /**
    + * GntAction:
    + *
    * An application can register actions which will show up in a 'start-menu' like popup
    */
    typedef struct _GntAction
    @@ -76,6 +78,22 @@
    void (*callback)(void);
    } GntAction;
    +typedef struct _GntListWindow {
    + GntWidget *window;
    + GntWidget *tree;
    +} GntListWindow;
    +
    +/**
    + * GntWM:
    + * @acts: List of actions
    + * @menu: Currently active menu. There can be at most one menu at a time on the
    + * screen. If there is a menu being displayed, then all the keystrokes
    + * will be sent to the menu until it is closed, either when the user
    + * activates a menuitem, or presses Escape to cancel the menu.
    + * @event_stack: Will be set to %TRUE when a user-event, ie. a mouse-click or a
    + * key-press is being processed. This variable will be used to
    + * determine whether to give focus to a new window.
    + */
    struct _GntWM
    {
    GntBindable inherit;
    @@ -86,32 +104,18 @@
    GList *tagged; /* tagged windows */
    GntWS *cws;
    - struct {
    - GntWidget *window;
    - GntWidget *tree;
    - } _list,
    - *windows, /* Window-list window */
    - *actions; /* Action-list window */
    + GntListWindow _list;
    + GntListWindow *windows, /* Window-list window */
    + GntListWindow *actions; /* Action-list window */
    GHashTable *nodes; /* GntWidget -> GntNode */
    GHashTable *name_places; /* window name -> ws*/
    GHashTable *title_places; /* window title -> ws */
    - GList *acts; /* List of actions */
    + GList *acts;
    - /**
    - * There can be at most one menu at a time on the screen.
    - * If there is a menu being displayed, then all the keystrokes will be sent to
    - * the menu until it is closed, either when the user activates a menuitem, or
    - * presses Escape to cancel the menu.
    - */
    - GntMenu *menu; /* Currently active menu */
    + GntMenu *menu;
    - /**
    - * 'event_stack' will be set to TRUE when a user-event, ie. a mouse-click
    - * or a key-press is being processed. This variable will be used to determine
    - * whether to give focus to a new window.
    - */
    gboolean event_stack;
    GntKeyPressMode mode;
    @@ -184,148 +188,187 @@
    G_BEGIN_DECLS
    /**
    + * gnt_wm_get_gtype:
    + *
    * Returns: GType for GntWM.
    */
    GType gnt_wm_get_gtype(void);
    /**
    - * Add a workspace.
    + * gnt_wm_add_workspace:
    * @wm: The window-manager.
    * @ws: The workspace to add.
    + *
    + * Add a workspace.
    */
    void gnt_wm_add_workspace(GntWM *wm, GntWS *ws);
    /**
    - * Switch to a workspace.
    + * gnt_wm_switch_workspace:
    * @wm: The window-manager.
    * @n: Index of the workspace to switch to.
    *
    + * Switch to a workspace.
    + *
    * Returns: %TRUE if the switch was successful.
    */
    gboolean gnt_wm_switch_workspace(GntWM *wm, gint n);
    /**
    + * gnt_wm_switch_workspace_prev:
    + * @wm: The window-manager.
    + *
    * Switch to the previous workspace from the current one.
    - * @wm: The window-manager.
    */
    gboolean gnt_wm_switch_workspace_prev(GntWM *wm);
    /**
    + * gnt_wm_switch_workspace_next:
    + * @wm: The window-manager.
    + *
    * Switch to the next workspace from the current one.
    - * @wm: The window-manager.
    */
    gboolean gnt_wm_switch_workspace_next(GntWM *wm);
    /**
    - * Move a window to a specific workspace.
    + * gnt_wm_widget_move_workspace:
    * @wm: The window manager.
    * @neww: The new workspace.
    * @widget: The widget to move.
    + *
    + * Move a window to a specific workspace.
    */
    void gnt_wm_widget_move_workspace(GntWM *wm, GntWS *neww, GntWidget *widget);
    /**
    - * Set the list of workspaces .
    + * gnt_wm_set_workspaces:
    * @wm: The window manager.
    * @workspaces: The list of workspaces.
    + *
    + * Set the list of workspaces .
    */
    void gnt_wm_set_workspaces(GntWM *wm, GList *workspaces);
    /**
    - * Find the workspace that contains a specific widget.
    + * gnt_wm_widget_find_workspace:
    * @wm: The window-manager.
    * @widget: The widget to find.
    + *
    + * Find the workspace that contains a specific widget.
    + *
    * Returns: The workspace that has the widget.
    */
    GntWS *gnt_wm_widget_find_workspace(GntWM *wm, GntWidget *widget);
    /**
    - * Process a new window.
    - *
    + * gnt_wm_new_window:
    * @wm: The window-manager.
    * @widget: The new window.
    + *
    + * Process a new window.
    */
    void gnt_wm_new_window(GntWM *wm, GntWidget *widget);
    /**
    - * Decorate a window.
    + * gnt_wm_window_decorate:
    * @wm: The window-manager.
    * @widget: The widget to decorate.
    + *
    + * Decorate a window.
    */
    void gnt_wm_window_decorate(GntWM *wm, GntWidget *widget);
    /**
    - * Close a window.
    + * gnt_wm_window_close:
    * @wm: The window-manager.
    * @widget: The window to close.
    + *
    + * Close a window.
    */
    void gnt_wm_window_close(GntWM *wm, GntWidget *widget);
    /**
    - * Process input.
    - *
    + * gnt_wm_process_input:
    * @wm: The window-manager.
    * @string: The input string to process.
    *
    + * Process input.
    + *
    * Returns: %TRUE of the string was processed, %FALSE otherwise.
    */
    gboolean gnt_wm_process_input(GntWM *wm, const char *string);
    /**
    - * Process a click event.
    + * gnt_wm_process_click:
    * @wm: The window manager.
    * @event: The mouse event.
    * @x: The x-coordinate of the mouse.
    * @y: The y-coordinate of the mouse.
    * @widget: The widget under the mouse.
    *
    + * Process a click event.
    + *
    * Returns: %TRUE if the event was handled, %FALSE otherwise.
    */
    gboolean gnt_wm_process_click(GntWM *wm, GntMouseEvent event, int x, int y, GntWidget *widget);
    /**
    - * Resize a window.
    + * gnt_wm_resize_window:
    * @wm: The window manager.
    * @widget: The window to resize.
    * @width: The desired width of the window.
    * @height: The desired height of the window.
    + *
    + * Resize a window.
    */
    void gnt_wm_resize_window(GntWM *wm, GntWidget *widget, int width, int height);
    /**
    - * Move a window.
    + * gnt_wm_move_window:
    * @wm: The window manager.
    * @widget: The window to move.
    * @x: The desired x-coordinate of the window.
    * @y: The desired y-coordinate of the window.
    + *
    + * Move a window.
    */
    void gnt_wm_move_window(GntWM *wm, GntWidget *widget, int x, int y);
    /**
    - * Update a window.
    + * gnt_wm_update_window:
    * @wm: The window-manager.
    * @widget: The window to update.
    + *
    + * Update a window.
    */
    void gnt_wm_update_window(GntWM *wm, GntWidget *widget);
    /**
    - * Raise a window.
    + * gnt_wm_raise_window:
    * @wm: The window-manager.
    * @widget: The window to raise.
    + *
    + * Raise a window.
    */
    void gnt_wm_raise_window(GntWM *wm, GntWidget *widget);
    /**
    + * gnt_wm_set_event_stack:
    + *
    * @internal
    */
    void gnt_wm_set_event_stack(GntWM *wm, gboolean set);
    /**
    + * gnt_wm_copy_win:
    + *
    * @internal
    */
    void gnt_wm_copy_win(GntWidget *widget, GntNode *node);
    /**
    + * gnt_wm_get_idle_time:
    + *
    * Returns: The idle time of the user.
    */
    time_t gnt_wm_get_idle_time(void);
    --- a/gntws.h Sun Feb 02 02:27:03 2014 +0530
    +++ b/gntws.h Sun Feb 02 03:34:37 2014 +0530
    @@ -70,110 +70,123 @@
    G_BEGIN_DECLS
    /**
    + * gnt_ws_get_gtype:
    + *
    * Returns: The GType for GntWS.
    *
    - * @since 2.0.0 (gnt), 2.1.0 (pidgin)
    + * Since: 2.0.0 (gnt), 2.1.0 (pidgin)
    */
    GType gnt_ws_get_gtype(void);
    /**
    - * Create a new workspace with the specified name.
    + * gnt_ws_new:
    + * @name: The desired name of the workspace, or %NULL.
    *
    - * @name: The desired name of the workspace, or %NULL.
    + * Create a new workspace with the specified name.
    *
    * Returns: The newly created workspace.
    *
    - * @since 2.0.0 (gnt), 2.1.0 (pidgin)
    + * Since: 2.0.0 (gnt), 2.1.0 (pidgin)
    */
    GntWS *gnt_ws_new(const char *name);
    /**
    - * Set the name of a workspace.
    - *
    + * gnt_ws_set_name:
    * @ws: The workspace to rename.
    * @name: The new name of the workspace.
    *
    - * @since 2.0.0 (gnt), 2.1.0 (pidgin)
    + * Set the name of a workspace.
    + *
    + * Since: 2.0.0 (gnt), 2.1.0 (pidgin)
    */
    void gnt_ws_set_name(GntWS *ws, const gchar *name);
    /**
    - * Add a widget to a workspace.
    - *
    + * gnt_ws_add_widget:
    * @ws: The workspace.
    * @widget: The widget to add.
    *
    - * @since 2.0.0 (gnt), 2.1.0 (pidgin)
    + * Add a widget to a workspace.
    + *
    + * Since: 2.0.0 (gnt), 2.1.0 (pidgin)
    */
    void gnt_ws_add_widget(GntWS *ws, GntWidget *widget);
    /**
    - * Remove a widget from a workspace.
    - *
    + * gnt_ws_remove_widget:
    * @ws: The workspace
    * @widget: The widget to remove from the workspace.
    *
    - * @since 2.0.0 (gnt), 2.1.0 (pidgin)
    + * Remove a widget from a workspace.
    + *
    + * Since: 2.0.0 (gnt), 2.1.0 (pidgin)
    */
    void gnt_ws_remove_widget(GntWS *ws, GntWidget *widget);
    /**
    - * Hide a widget in a workspace.
    - *
    + * gnt_ws_widget_hide:
    * @widget: The widget to hide.
    * @nodes: A hashtable containing information about the widgets.
    *
    - * @since 2.0.0 (gnt), 2.1.0 (pidgin)
    + * Hide a widget in a workspace.
    + *
    + * Since: 2.0.0 (gnt), 2.1.0 (pidgin)
    */
    void gnt_ws_widget_hide(GntWidget *widget, GHashTable *nodes);
    /**
    - * Show a widget in a workspace.
    - *
    + * gnt_ws_widget_show:
    * @widget: The widget to show.
    * @nodes: A hashtable containing information about the widgets.
    *
    - * @since 2.0.0 (gnt), 2.1.0 (pidgin)
    + * Show a widget in a workspace.
    + *
    + * Since: 2.0.0 (gnt), 2.1.0 (pidgin)
    */
    void gnt_ws_widget_show(GntWidget *widget, GHashTable *nodes);
    /**
    - * Draw the taskbar in a workspace.
    - *
    + * gnt_ws_draw_taskbar:
    * @ws: The workspace.
    * @reposition: Whether the workspace should reposition the taskbar.
    *
    - * @since 2.0.0 (gnt), 2.1.0 (pidgin)
    + * Draw the taskbar in a workspace.
    + *
    + * Since: 2.0.0 (gnt), 2.1.0 (pidgin)
    */
    void gnt_ws_draw_taskbar(GntWS *ws, gboolean reposition);
    /**
    - * Hide a workspace.
    - *
    + * gnt_ws_hide:
    * @ws: The workspace to hide.
    * @table: A hashtable containing information about the widgets.
    *
    - * @since 2.0.0 (gnt), 2.1.0 (pidgin)
    + * Hide a workspace.
    + *
    + * Since: 2.0.0 (gnt), 2.1.0 (pidgin)
    */
    void gnt_ws_hide(GntWS *ws, GHashTable *table);
    /**
    - * Show a workspace.
    - *
    + * gnt_ws_show:
    * @ws: The workspace to hide.
    * @table: A hashtable containing information about the widgets.
    *
    - * @since 2.0.0 (gnt), 2.1.0 (pidgin)
    + * Show a workspace.
    + *
    + * Since: 2.0.0 (gnt), 2.1.0 (pidgin)
    */
    void gnt_ws_show(GntWS *ws, GHashTable *table);
    /**
    + * gnt_ws_get_name:
    + * @ws: The workspace.
    + *
    * Get the name of a workspace.
    *
    - * @ws: The workspace.
    * Returns: The name of the workspace (can be %NULL).
    *
    - * @since 2.0.0 (gnt), 2.1.0 (pidgin)
    + * Since: 2.0.0 (gnt), 2.1.0 (pidgin)
    */
    const char * gnt_ws_get_name(GntWS *ws);