qulogic/libgnt

Fix some annotation warnings in libgnt
gtkdoc-conversion
2014-02-09, Ankit Vani
897506743c58
Parents ff2db1462fd5
Children 6d61183df72df466d327b66075eaa1e6f79a
Fix some annotation warnings in libgnt
10 files changed, 64 insertions(+), 52 deletions(-)
  • +3 -2
    gnt.h
  • +6 -6
    gntbindable.h
  • +1 -1
    gntcombobox.h
  • +3 -2
    gntfilesel.h
  • +1 -1
    gntmenu.h
  • +4 -4
    gntmenuitem.h
  • +6 -5
    gntstyle.h
  • +27 -19
    gnttree.h
  • +10 -9
    gntutils.h
  • +3 -3
    gntwm.h
    • --- a/gnt.h Sun Feb 09 21:12:35 2014 +0530
    +++ b/gnt.h Sun Feb 09 23:53:18 2014 +0530
    @@ -171,7 +171,7 @@
    *
    * Get the global clipboard.
    *
    - * Returns: The clipboard.
    + * Returns: (transfer none): The clipboard.
    */
    GntClipboard * gnt_get_clipboard(void);
    @@ -180,7 +180,8 @@
    *
    * 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);
    --- a/gntbindable.h Sun Feb 09 21:12:35 2014 +0530
    +++ b/gntbindable.h Sun Feb 09 23:53:18 2014 +0530
    @@ -120,11 +120,11 @@
    /**
    * 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 @@
    *
    * 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);
    --- a/gntcombobox.h Sun Feb 09 21:12:35 2014 +0530
    +++ b/gntcombobox.h Sun Feb 09 23:53:18 2014 +0530
    @@ -120,7 +120,7 @@
    *
    * 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);
    --- a/gntfilesel.h Sun Feb 09 21:12:35 2014 +0530
    +++ b/gntfilesel.h Sun Feb 09 23:53:18 2014 +0530
    @@ -185,8 +185,9 @@
    *
    * 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);
    --- a/gntmenu.h Sun Feb 09 21:12:35 2014 +0530
    +++ b/gntmenu.h Sun Feb 09 23:53:18 2014 +0530
    @@ -125,7 +125,7 @@
    *
    * 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
    */
    --- a/gntmenuitem.h Sun Feb 09 21:12:35 2014 +0530
    +++ b/gntmenuitem.h Sun Feb 09 23:53:18 2014 +0530
    @@ -108,9 +108,9 @@
    /**
    * 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 @@
    *
    * Get the submenu for a menuitem.
    *
    - * Returns: The submenu, or %NULL.
    + * Returns: (transfer none): The submenu, or %NULL.
    *
    * Since: 2.3.0
    */
    --- a/gntstyle.h Sun Feb 09 21:12:35 2014 +0530
    +++ b/gntstyle.h Sun Feb 09 23:53:18 2014 +0530
    @@ -76,14 +76,15 @@
    /**
    * 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
    */
    --- a/gnttree.h Sun Feb 09 21:12:35 2014 +0530
    +++ b/gnttree.h Sun Feb 09 23:53:18 2014 +0530
    @@ -206,7 +206,7 @@
    *
    * 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 @@
    * 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 @@
    *
    * 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 @@
    *
    * 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 @@
    *
    * 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 @@
    /**
    * 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 @@
    /**
    * 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 @@
    *
    * 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
    */
    --- a/gntutils.h Sun Feb 09 21:12:35 2014 +0530
    +++ b/gntutils.h Sun Feb 09 23:53:18 2014 +0530
    @@ -88,17 +88,17 @@
    /**
    * 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 @@
    *
    * 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);
    --- a/gntwm.h Sun Feb 09 21:12:35 2014 +0530
    +++ b/gntwm.h Sun Feb 09 23:53:18 2014 +0530
    @@ -248,8 +248,8 @@
    /**
    * gnt_wm_set_workspaces:
    - * @wm: The window manager.
    - * @workspaces: The list of workspaces.
    + * @wm: The window manager.
    + * @workspaces: (element-type Gnt.WS): The list of workspaces.
    *
    * Set the list of workspaces .
    */
    @@ -262,7 +262,7 @@
    *
    * Find the workspace that contains a specific widget.
    *
    - * Returns: The workspace that has the widget.
    + * Returns: (transfer none): The workspace that has the widget.
    */
    GntWS *gnt_wm_widget_find_workspace(GntWM *wm, GntWidget *widget);