--- a/finch/libgnt/gnttree.h Fri Jan 31 17:56:27 2014 +0530
+++ b/finch/libgnt/gnttree.h Fri Jan 31 18:14:33 2014 +0530
@@ -102,14 +102,14 @@
G_BEGIN_DECLS
/**
- * @return The GType for GntTree
+ * Returns: The GType for GntTree
*/
GType gnt_tree_get_gtype(void);
/**
* Create a tree with one column.
*
- * @return The newly created tree
+ * Returns: The newly created tree
*
* @see gnt_tree_new_with_columns
*/
@@ -118,9 +118,9 @@
/**
* Create a tree with a specified number of columns.
*
- * @param columns Number of columns
+ * @columns: Number of columns
*
- * @return The newly created tree
+ * Returns: The newly created tree
*
* @see gnt_tree_new
*/
@@ -129,25 +129,25 @@
/**
* The number of rows the tree should display at a time.
*
- * @param tree The tree
- * @param rows The number of rows
+ * @tree: The tree
+ * @rows: The number of rows
*/
void gnt_tree_set_visible_rows(GntTree *tree, int rows);
/**
* Get the number visible rows.
*
- * @param tree The tree
+ * @tree: The tree
*
- * @return The number of visible rows
+ * Returns: The number of visible rows
*/
int gnt_tree_get_visible_rows(GntTree *tree);
/**
* Scroll the contents of the tree.
*
- * @param tree The tree
- * @param count If positive, the tree will be scrolled down by count rows,
+ * @tree: The tree
+ * @count: If positive, the tree will be scrolled down by count rows,
* otherwise, it will be scrolled up by count rows.
*/
void gnt_tree_scroll(GntTree *tree, int count);
@@ -155,13 +155,13 @@
/**
* Insert a row in the tree.
*
- * @param tree The tree
- * @param key The key for the row
- * @param row The row to insert
- * @param parent The key for the parent row
- * @param bigbro The key for the row to insert the new 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.
*
- * @return The inserted row
+ * Returns: The inserted row
*
* @see gnt_tree_create_row
* @see gnt_tree_add_row_last
@@ -172,12 +172,12 @@
/**
* Insert a row at the end of the tree.
*
- * @param tree The tree
- * @param key The key for the row
- * @param row The row to insert
- * @param parent The key for the parent row
+ * @tree: The tree
+ * @key: The key for the row
+ * @row: The row to insert
+ * @parent: The key for the parent row
*
- * @return The inserted row
+ * Returns: The inserted row
*
* @see gnt_tree_create_row
* @see gnt_tree_add_row_after
@@ -188,18 +188,18 @@
/**
* Get the key for the selected row.
*
- * @param tree The tree
+ * @tree: The tree
*
- * @return 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.
*
- * @param tree The tree
+ * @tree: The tree
*
- * @return The text, which needs to be freed by the caller
+ * Returns: The text, which needs to be freed by the caller
* @see gnt_tree_get_row_text_list
* @see gnt_tree_get_selection_text_list
*/
@@ -208,12 +208,12 @@
/**
* Get a list of text for a row.
*
- * @param tree The tree
- * @param key A key corresponding to the row in question. If key
- * is @c NULL, the text list for the selected row will
+ * @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.
*
- * @return A list of texts of a row. The list and its data should be
+ * 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
@@ -224,10 +224,10 @@
/**
* Get the key of a row.
*
- * @param tree The tree
- * @param row The GntTreeRow object
+ * @tree: The tree
+ * @row: The GntTreeRow object
*
- * @return The key of the row.
+ * Returns: The key of the row.
* @since 2.8.0 (gnt), 2.7.2 (pidgin)
*/
gpointer gnt_tree_row_get_key(GntTree *tree, GntTreeRow *row);
@@ -235,10 +235,10 @@
/**
* Get the next row.
*
- * @param tree The tree
- * @param row The GntTreeRow object
+ * @tree: The tree
+ * @row: The GntTreeRow object
*
- * @return The next row.
+ * Returns: The next row.
* @since 2.8.0 (gnt), 2.7.2 (pidgin)
*/
GntTreeRow * gnt_tree_row_get_next(GntTree *tree, GntTreeRow *row);
@@ -246,10 +246,10 @@
/**
* Get the previous row.
*
- * @param tree The tree
- * @param row The GntTreeRow object
+ * @tree: The tree
+ * @row: The GntTreeRow object
*
- * @return The previous row.
+ * Returns: The previous row.
* @since 2.8.0 (gnt), 2.7.2 (pidgin)
*/
GntTreeRow * gnt_tree_row_get_prev(GntTree *tree, GntTreeRow *row);
@@ -257,10 +257,10 @@
/**
* Get the child row.
*
- * @param tree The tree
- * @param row The GntTreeRow object
+ * @tree: The tree
+ * @row: The GntTreeRow object
*
- * @return The child row.
+ * Returns: The child row.
* @since 2.8.0 (gnt), 2.7.2 (pidgin)
*/
GntTreeRow * gnt_tree_row_get_child(GntTree *tree, GntTreeRow *row);
@@ -268,10 +268,10 @@
/**
* Get the parent row.
*
- * @param tree The tree
- * @param row The GntTreeRow object
+ * @tree: The tree
+ * @row: The GntTreeRow object
*
- * @return The parent row.
+ * Returns: The parent row.
* @since 2.8.0 (gnt), 2.7.2 (pidgin)
*/
GntTreeRow * gnt_tree_row_get_parent(GntTree *tree, GntTreeRow *row);
@@ -279,9 +279,9 @@
/**
* Get a list of text of the current row.
*
- * @param tree The tree
+ * @tree: The tree
*
- * @return A list of texts of the currently selected row. The list
+ * 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.
@@ -293,56 +293,56 @@
/**
* Returns the list of rows in the tree.
*
- * @param tree The tree
+ * @tree: The tree
*
- * @return The list of the rows. The list should not be modified by the caller.
+ * 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.
*
- * @param tree The tree
- * @param key The key for the row to remove
+ * @tree: The tree
+ * @key: The key for the row to remove
*/
void gnt_tree_remove(GntTree *tree, gpointer key);
/**
* Remove all the item from the tree.
*
- * @param tree The tree
+ * @tree: The tree
*/
void gnt_tree_remove_all(GntTree *tree);
/**
* Get the visible line number of the selected row.
*
- * @param tree The tree
+ * @tree: The tree
*
- * @return The line number of the currently 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.
*
- * @param tree The tree
- * @param key The key for the row
- * @param colno The index of the column
- * @param text The new text
+ * @tree: The tree
+ * @key: The key for the row
+ * @colno: The index of the column
+ * @text: The new text
*/
void gnt_tree_change_text(GntTree *tree, gpointer key, int colno, const char *text);
/**
* Add a checkable item in the tree.
*
- * @param tree The tree
- * @param key The key for the row
- * @param row The row to add
- * @param parent The parent of the row, or @c NULL
- * @param bigbro The row to insert after, or @c NULL
+ * @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
*
- * @return The row inserted.
+ * Returns: The row inserted.
*
* @see gnt_tree_create_row
* @see gnt_tree_create_row_from_list
@@ -354,37 +354,37 @@
/**
* Set whether a checkable item is checked or not.
*
- * @param tree The tree
- * @param key The key for the row
- * @param set @c TRUE if the item should be checked, @c FALSE if not
+ * @tree: The tree
+ * @key: The key for the row
+ * @set: %TRUE if the item should be checked, %FALSE if 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.
*
- * @param tree The tree
- * @param key The key for the row
+ * @tree: The tree
+ * @key: The key for the row
*
- * @return @c TRUE if the row is checked, @c FALSE otherwise.
+ * 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.
*
- * @param tree The tree
- * @param key The key for the row
- * @param flags The flags to set
+ * @tree: The tree
+ * @key: The key for the row
+ * @flags: The flags to set
*/
void gnt_tree_set_row_flags(GntTree *tree, void *key, GntTextFormatFlags flags);
/**
* Set color for the text in a row in the tree.
*
- * @param tree The tree
- * @param key The key for the row
- * @param color The color
+ * @tree: The tree
+ * @key: The key for the row
+ * @color: The color
* @since 2.4.0
*/
void gnt_tree_set_row_color(GntTree *tree, void *key, int color);
@@ -392,18 +392,18 @@
/**
* Select a row.
*
- * @param tree The tree
- * @param key The key of the row to select
+ * @tree: The tree
+ * @key: The key of the row to select
*/
void gnt_tree_set_selected(GntTree *tree , void *key);
/**
* Create a row to insert in the tree.
*
- * @param tree The tree
- * @param ... A string for each column in the tree
+ * @tree: The tree
+ * @...: A string for each column in the tree
*
- * @return The row
+ * Returns: The row
*
* @see gnt_tree_create_row_from_list
* @see gnt_tree_add_row_after
@@ -415,10 +415,10 @@
/**
* Create a row from a list of text.
*
- * @param tree The tree
- * @param list The list containing the text for each column
+ * @tree: The tree
+ * @list: The list containing the text for each column
*
- * @return The row
+ * Returns: The row
*
* @see gnt_tree_create_row
* @see gnt_tree_add_row_after
@@ -430,9 +430,9 @@
/**
* Set the width of a column in the tree.
*
- * @param tree The tree
- * @param col The index of the column
- * @param width The width for the column
+ * @tree: The tree
+ * @col: The index of the column
+ * @width: The width for the column
*
* @see gnt_tree_set_column_width_ratio
* @see gnt_tree_set_column_resizable
@@ -442,9 +442,9 @@
/**
* Set the title for a column.
*
- * @param tree The tree
- * @param index The index of the column
- * @param title The title for the column
+ * @tree: The tree
+ * @index: The index of the column
+ * @title: The title for the column
*
* @see gnt_tree_set_column_titles
* @see gnt_tree_set_show_title
@@ -456,8 +456,8 @@
/**
* Set the titles of the columns
*
- * @param tree The tree
- * @param ... One title for each column in the tree
+ * @tree: The tree
+ * @...: One title for each column in the tree
*
* @see gnt_tree_set_column_title
* @see gnt_tree_set_show_title
@@ -467,8 +467,8 @@
/**
* Set whether to display the title of the columns.
*
- * @param tree The tree
- * @param set If @c TRUE, the column titles are displayed
+ * @tree: The tree
+ * @set: If %TRUE, the column titles are displayed
*
* @see gnt_tree_set_column_title
* @see gnt_tree_set_column_titles
@@ -478,8 +478,8 @@
/**
* Set the compare function for sorting the data.
*
- * @param tree The tree
- * @param func The comparison function, which is used to compare
+ * @tree: The tree
+ * @func: The comparison function, which is used to compare
* the keys
*
* @see gnt_tree_sort_row
@@ -489,25 +489,25 @@
/**
* Set whether a row, which has child rows, should be expanded.
*
- * @param tree The tree
- * @param key The key of the row
- * @param expanded Whether to expand the child rows
+ * @tree: The tree
+ * @key: The key of the row
+ * @expanded: Whether to expand the child rows
*/
void gnt_tree_set_expanded(GntTree *tree, void *key, gboolean expanded);
/**
* Set whether to show column separators.
*
- * @param tree The tree
- * @param set If @c TRUE, the column separators are displayed
+ * @tree: The tree
+ * @set: If %TRUE, the column separators are displayed
*/
void gnt_tree_set_show_separator(GntTree *tree, gboolean set);
/**
* Sort a row in the tree.
*
- * @param tree The tree
- * @param row The row to sort
+ * @tree: The tree
+ * @row: The row to sort
*
* @see gnt_tree_set_compare_func
*/
@@ -516,17 +516,17 @@
/**
* Automatically adjust the width of the columns in the tree.
*
- * @param tree The tree
+ * @tree: The tree
*/
void gnt_tree_adjust_columns(GntTree *tree);
/**
* Set the hash functions to use to hash, compare and free the keys.
*
- * @param tree The tree
- * @param hash The hashing function
- * @param eq The function to compare keys
- * @param kd The function to use to free the keys when a row is removed
+ * @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
*/
void gnt_tree_set_hash_fns(GntTree *tree, gpointer hash, gpointer eq, gpointer kd);
@@ -536,9 +536,9 @@
* This can be useful when, for example, we want to store some data
* which we don't want/need to display.
*
- * @param tree The tree
- * @param col The index of the column
- * @param vis If @c FALSE, the column will not be displayed
+ * @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);
@@ -546,9 +546,9 @@
* Set whether a column can be resized to keep the same ratio when the
* tree is resized.
*
- * @param tree The tree
- * @param col The index of the column
- * @param res If @c FALSE, the column will not be resized when the
+ * @tree: The tree
+ * @col: The index of the column
+ * @res: If %FALSE, the column will not be resized when the
* tree is resized
*
* @see gnt_tree_set_col_width
@@ -562,18 +562,18 @@
* 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.
*
- * @param tree The tree
- * @param col The index of the column
- * @param bin @c TRUE if the data for the column is binary
+ * @tree: The tree
+ * @col: The index of the column
+ * @bin: %TRUE if the data for the column is binary
*/
void gnt_tree_set_column_is_binary(GntTree *tree, int col, gboolean bin);
/**
* Set whether text in a column should be right-aligned.
*
- * @param tree The tree
- * @param col The index of the column
- * @param right @c TRUE if the text in the column should be 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)
*/
@@ -583,8 +583,8 @@
* Set column widths to use when calculating column widths after a tree
* is resized.
*
- * @param tree The tree
- * @param cols Array of widths. The width must have the same number
+ * @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.
*
@@ -598,8 +598,8 @@
/**
* Set the column to use for typeahead searching.
*
- * @param tree The tree
- * @param col The index of the column
+ * @tree: The tree
+ * @col: The index of the column
*
* @since 2.0.0 (gnt), 2.1.0 (pidgin)
*/
@@ -608,8 +608,8 @@
/**
* Check whether the user is currently in the middle of a search.
*
- * @param tree The tree
- * @return @c TRUE if the user is searching, @c FALSE otherwise.
+ * @tree: The tree
+ * Returns: %TRUE if the user is searching, %FALSE otherwise.
*
* @since 2.0.0 (gnt), 2.1.0 (pidgin)
*/
@@ -618,11 +618,11 @@
/**
* Set a custom search function.
*
- * @param tree The tree
- * @param func The custom search function. The search function is
+ * @tree: The tree
+ * @func: The custom search function. The search function is
* sent the tree itself, the key of a row, the search
* string and the content of row in the search column.
- * If the function returns @c TRUE, the row is dislayed,
+ * If the function returns %TRUE, the row is dislayed,
* otherwise it's not.
*
* @since 2.0.0 (gnt), 2.1.0 (pidgin)
@@ -633,10 +633,10 @@
/**
* Get the parent key for a row.
*
- * @param tree The tree
- * @param key The key for the row.
+ * @tree: The tree
+ * @key: The key for the row.
*
- * @return The key of the parent row.
+ * Returns: The key of the parent row.
* @since 2.4.0
*/
gpointer gnt_tree_get_parent_key(GntTree *tree, gpointer key);
