/soc/2013/ankitkv/gobjectification: 0858f6d91e32: Fix some annot...
Ankit Vani
a at nevitus.org
Sun Feb 9 13:47:20 EST 2014
Changeset: 0858f6d91e323d81d0334bb73a6f3346191d02db
Author: Ankit Vani <a at nevitus.org>
Date: 2014-02-09 23:53 +0530
Branch: gtkdoc-conversion
URL: https://hg.pidgin.im/soc/2013/ankitkv/gobjectification/rev/0858f6d91e32
Description:
Fix some annotation warnings in libgnt
diffstat:
finch/libgnt/gnt.h | 5 +++--
finch/libgnt/gntbindable.h | 12 ++++++------
finch/libgnt/gntcombobox.h | 2 +-
finch/libgnt/gntfilesel.h | 5 +++--
finch/libgnt/gntmenu.h | 2 +-
finch/libgnt/gntmenuitem.h | 8 ++++----
finch/libgnt/gntstyle.h | 11 ++++++-----
finch/libgnt/gnttree.h | 46 +++++++++++++++++++++++++++-------------------
finch/libgnt/gntutils.h | 19 ++++++++++---------
finch/libgnt/gntwm.h | 6 +++---
10 files changed, 64 insertions(+), 52 deletions(-)
diffs (truncated from 319 to 300 lines):
diff --git a/finch/libgnt/gnt.h b/finch/libgnt/gnt.h
--- a/finch/libgnt/gnt.h
+++ b/finch/libgnt/gnt.h
@@ -171,7 +171,7 @@ void gnt_quit(void);
*
* Get the global clipboard.
*
- * Returns: The clipboard.
+ * Returns: (transfer none): The clipboard.
*/
GntClipboard * gnt_get_clipboard(void);
@@ -180,7 +180,8 @@ GntClipboard * gnt_get_clipboard(void);
*
* Get the string in the clipboard.
*
- * Returns: A copy of the string in the clipboard. The caller must 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);
diff --git a/finch/libgnt/gntbindable.h b/finch/libgnt/gntbindable.h
--- a/finch/libgnt/gntbindable.h
+++ b/finch/libgnt/gntbindable.h
@@ -120,11 +120,11 @@ void gnt_bindable_action_param_free(GntB
/**
* 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.
+ * @klass: The class the binding is for.
+ * @name: The name of the binding.
+ * @callback: (scope call): 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.
*/
@@ -179,7 +179,7 @@ gboolean gnt_bindable_perform_action_nam
*
* Returns a GntTree populated with "key" -> "binding" for the widget.
*
- * Returns: The GntTree.
+ * Returns: (transfer full): The GntTree.
*/
GntBindable * gnt_bindable_bindings_view(GntBindable *bind);
diff --git a/finch/libgnt/gntcombobox.h b/finch/libgnt/gntcombobox.h
--- a/finch/libgnt/gntcombobox.h
+++ b/finch/libgnt/gntcombobox.h
@@ -120,7 +120,7 @@ void gnt_combo_box_remove_all(GntComboBo
*
* Get the data that is currently selected
*
- * Returns: The data of the currently selected entry
+ * Returns: (transfer none): The data of the currently selected entry
*/
gpointer gnt_combo_box_get_selected_data(GntComboBox *box);
diff --git a/finch/libgnt/gntfilesel.h b/finch/libgnt/gntfilesel.h
--- a/finch/libgnt/gntfilesel.h
+++ b/finch/libgnt/gntfilesel.h
@@ -185,8 +185,9 @@ char * gnt_file_sel_get_selected_file(Gn
*
* 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.
+ * Returns: (transfer full) (element-type filename): A list of paths for the
+ * selected files. The caller must g_free() the contents of the list,
+ * and g_list_free() the list.
*/
GList * gnt_file_sel_get_selected_multi_files(GntFileSel *sel);
diff --git a/finch/libgnt/gntmenu.h b/finch/libgnt/gntmenu.h
--- a/finch/libgnt/gntmenu.h
+++ b/finch/libgnt/gntmenu.h
@@ -125,7 +125,7 @@ void gnt_menu_add_item(GntMenu *menu, Gn
*
* Return the GntMenuItem with the given ID.
*
- * Returns: The menuitem with the given ID, or %NULL.
+ * Returns: (transfer none): The menuitem with the given ID, or %NULL.
*
* Since: 2.3.0
*/
diff --git a/finch/libgnt/gntmenuitem.h b/finch/libgnt/gntmenuitem.h
--- a/finch/libgnt/gntmenuitem.h
+++ b/finch/libgnt/gntmenuitem.h
@@ -108,9 +108,9 @@ GntMenuItem * gnt_menuitem_new(const cha
/**
* gnt_menuitem_set_callback:
- * @item: The menuitem.
- * @callback: The callback function.
- * @data: Data to send to the callback function.
+ * @item: The menuitem.
+ * @callback: (scope call): The callback function.
+ * @data: Data to send to the callback function.
*
* Set a callback function for a menuitem.
*/
@@ -131,7 +131,7 @@ void gnt_menuitem_set_submenu(GntMenuIte
*
* Get the submenu for a menuitem.
*
- * Returns: The submenu, or %NULL.
+ * Returns: (transfer none): The submenu, or %NULL.
*
* Since: 2.3.0
*/
diff --git a/finch/libgnt/gntstyle.h b/finch/libgnt/gntstyle.h
--- a/finch/libgnt/gntstyle.h
+++ b/finch/libgnt/gntstyle.h
@@ -76,14 +76,15 @@ char *gnt_style_get_from_name(const char
/**
* 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
+ * @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().
+ * Returns: (transfer full): %NULL terminated string array. The array should be
+ * freed with g_strfreev().
*
* Since: 2.4.0
*/
diff --git a/finch/libgnt/gnttree.h b/finch/libgnt/gnttree.h
--- a/finch/libgnt/gnttree.h
+++ b/finch/libgnt/gnttree.h
@@ -206,7 +206,7 @@ GntTreeRow * gnt_tree_add_row_last(GntTr
*
* Get the key for the selected row.
*
- * Returns: The key for the selected row
+ * Returns: (transfer none): The key for the selected row
*/
gpointer gnt_tree_get_selection_data(GntTree *tree);
@@ -226,17 +226,21 @@ char * gnt_tree_get_selection_text(GntTr
* 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.
+ * 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(), 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.
+ * Returns: (transfer container) (element-type utf8): 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.
*/
+/* TODO This leaks when used from introspection. The transfer mode for the
+ return type here should be 'full', but that would free binary data as
+ well. */
GList * gnt_tree_get_row_text_list(GntTree *tree, gpointer key);
/**
@@ -246,7 +250,7 @@ GList * gnt_tree_get_row_text_list(GntTr
*
* Get the key of a row.
*
- * Returns: The key of the row.
+ * Returns: (transfer none): The key of the row.
*
* Since: 2.8.0 (gnt), 2.7.2 (pidgin)
*/
@@ -312,11 +316,14 @@ GntTreeRow * gnt_tree_row_get_parent(Gnt
*
* See gnt_tree_get_row_text_list(), 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.
+ * Returns: (transfer container) (element-type utf8): 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.
*/
+/* TODO This leaks when used from introspection. The transfer mode for the
+ return type here should be 'full', but that would free binary data as
+ well. */
GList * gnt_tree_get_selection_text_list(GntTree *tree);
/**
@@ -325,7 +332,8 @@ GList * gnt_tree_get_selection_text_list
*
* Returns the list of rows in the tree.
*
- * Returns: The list of the rows. The list should not be modified by the caller.
+ * Returns: (transfer none) (element-type Gnt.TreeRow): The list of the rows.
+ * The list should not be modified by the caller.
*/
GList *gnt_tree_get_rows(GntTree *tree);
@@ -452,15 +460,15 @@ GntTreeRow * gnt_tree_create_row(GntTree
/**
* gnt_tree_create_row_from_list:
- * @tree: The tree
- * @list: The list containing the text for each column
+ * @tree: The tree
+ * @list: (element-type utf8): The list containing the text for each column
*
* Create a row from a list of text.
*
* See gnt_tree_create_row(), gnt_tree_add_row_after(), gnt_tree_add_row_last(),
* gnt_tree_add_choice().
*
- * Returns: The row
+ * Returns: (transfer full): The row
*/
GntTreeRow * gnt_tree_create_row_from_list(GntTree *tree, GList *list);
@@ -514,9 +522,9 @@ void gnt_tree_set_show_title(GntTree *tr
/**
* gnt_tree_set_compare_func:
- * @tree: The tree
- * @func: The comparison function, which is used to compare
- * the keys
+ * @tree: The tree
+ * @func: (scope call): The comparison function, which is used to compare
+ * the keys
*
* Set the compare function for sorting the data.
*
@@ -687,7 +695,7 @@ void gnt_tree_set_search_function(GntTre
*
* Get the parent key for a row.
*
- * Returns: The key of the parent row.
+ * Returns: (transfer none): The key of the parent row.
*
* Since: 2.4.0
*/
diff --git a/finch/libgnt/gntutils.h b/finch/libgnt/gntutils.h
--- a/finch/libgnt/gntutils.h
+++ b/finch/libgnt/gntutils.h
@@ -88,17 +88,17 @@ char * gnt_util_onscreen_fit_string(cons
/**
* gnt_hash_table_duplicate:
- * @src: The source hashtable.
- * @hash: The hash-function to use.
- * @equal: The hash-equal function to use.
- * @key_d: The key-destroy function to use.
- * @value_d: The value-destroy function to use.
- * @key_dup: The function to use to duplicate the key.
- * @value_dup: The function to use to duplicate the value.
+ * @src: The source hashtable.
+ * @hash: (scope call): The hash-function to use.
+ * @equal: The hash-equal function to use.
+ * @key_d: The key-destroy function to use.
+ * @value_d: The value-destroy function to use.
+ * @key_dup: (scope call): The function to use to duplicate the key.
+ * @value_dup: (scope call): The function to use to duplicate the value.
*
* Duplicate the contents of a hastable.
*
- * Returns: The new hashtable.
+ * Returns: (transfer full): The new hashtable.
*/
GHashTable * gnt_hash_table_duplicate(GHashTable *src, GHashFunc hash, GEqualFunc equal, GDestroyNotify key_d, GDestroyNotify value_d, GntDuplicateFunc key_dup, GntDuplicateFunc value_dup);
@@ -116,7 +116,8 @@ gboolean gnt_boolean_handled_accumulator
*
* Get a helpful display about the bindings of a widget.
*
- * Returns: Returns a GntTree populated with "key" -> "binding" for the widget.
+ * Returns: (transfer full): Returns a GntTree populated with "key" -> "binding"
+ * for the widget.
*/
GntWidget * gnt_widget_bindings_view(GntWidget *widget);
diff --git a/finch/libgnt/gntwm.h b/finch/libgnt/gntwm.h
--- a/finch/libgnt/gntwm.h
+++ b/finch/libgnt/gntwm.h
@@ -248,8 +248,8 @@ void gnt_wm_widget_move_workspace(GntWM
More information about the Commits
mailing list