Fix various mis[sing ]annotations and style issues in GIR

12 files changed, 98 insertions, 52 deletions

diff --git a/midori/midori-app.c b/midori/midori-app.c
index a4c71df5..b129b31f 100644
--- a/midori/midori-app.c
+++ b/midori/midori-app.c
@@ -1061,7 +1061,7 @@ midori_app_create_browser (MidoriApp* app)
  *
  * Retrieves the browsers as a list.
  *
- * Return value: a newly allocated #Glist of #MidoriBrowser
+ * Return value: (transfer container) (element-type Midori.Browser): a newly allocated #Glist of #MidoriBrowser
  *
  * Since: 0.2.5
  **/
diff --git a/midori/midori-bookmarks-db.c b/midori/midori-bookmarks-db.c
index 7a633d06..1d4be61e 100644
--- a/midori/midori-bookmarks-db.c
+++ b/midori/midori-bookmarks-db.c
@@ -880,7 +880,7 @@ midori_bookmarks_db_array_from_sqlite (MidoriBookmarksDb* bookmarks,
 
 /**
  * midori_bookmarks_db_query_recursive:
- * @array: the main bookmark array
+ * @bookmarks: the main bookmark array
  * @fields: comma separated list of fields
  * @condition: condition, like "folder = '%q'"
  * @value: a value to be inserted if @condition contains %q
diff --git a/midori/midori-bookmarks-db.h b/midori/midori-bookmarks-db.h
index 988518f3..4a038658 100644
--- a/midori/midori-bookmarks-db.h
+++ b/midori/midori-bookmarks-db.h
@@ -41,7 +41,7 @@ MidoriBookmarksDb*
 midori_bookmarks_db_new (char** errmsg);
 
 void
-midori_bookmarks_db_on_quit (MidoriBookmarksDb* array);
+midori_bookmarks_db_on_quit (MidoriBookmarksDb* bookmarks);
 
 void
 midori_bookmarks_db_add_item (MidoriBookmarksDb* bookmarks, KatzeItem* item);
diff --git a/midori/midori-browser.c b/midori/midori-browser.c
index 389475ad..7169587e 100644
--- a/midori/midori-browser.c
+++ b/midori/midori-browser.c
@@ -3119,7 +3119,7 @@ _action_find_previous_activate (GtkAction*     action,
  *
  * Retrieves a list of actions which are suitable for use in a toolbar.
  *
- * Return value: a NULL-terminated array of strings with actions
+ * Return value: (array zero-terminated=1) (transfer none): a NULL-terminated array of strings with actions
  *
  * Since: 0.1.8
  **/
@@ -7031,13 +7031,13 @@ midori_browser_add_tab (MidoriBrowser* browser,
 /**
  * midori_browser_page_num:
  * @browser: a #MidoriBrowser
- * @widget: a widget in the browser
+ * @view: a child widget of the browser's notebook
  *
- * Retrieves the position of @widget in the browser.
+ * Retrieves the position of @view in the browser.
  *
  * If there is no page present at all, -1 is returned.
  *
- * Return value: the index of the widget, or -1
+ * Return value: the index of the view, or -1
  *
  * Since: 0.4.5
  **/
@@ -7075,7 +7075,7 @@ midori_browser_close_tab (MidoriBrowser* browser,
  * @browser: a #MidoriBrowser
  * @item: an item
  *
- * Return value: a #GtkWidget
+ * Return value: (type MidoriView) (transfer none): the added view
  *
  * Since: 0.4.9: Return type is GtkWidget*
  **/
@@ -7103,7 +7103,7 @@ midori_browser_add_item (MidoriBrowser* browser,
  *
  * Appends an uri in the form of a new view.
  *
- * Return value: a #GtkWidget
+ * Return value: (type MidoriView) (transfer none): the added view
  *
  * Since: 0.4.9: Return type is GtkWidget*
  **/
@@ -7153,7 +7153,7 @@ midori_browser_set_action_visible (MidoriBrowser* browser,
 /**
  * midori_browser_block_action:
  * @browser: a #MidoriBrowser
- * @name: the action to be blocked
+ * @action: the action to be blocked
  *
  * Blocks built-in behavior of the specified action without
  * disabling it, which gives you a chance to connect your
@@ -7185,7 +7185,7 @@ midori_browser_block_action (MidoriBrowser* browser,
 /**
  * midori_browser_unblock_action:
  * @browser: a #MidoriBrowser
- * @name: the action to be unblocked
+ * @action: the action to be unblocked
  *
  * Restores built-in behavior of the specified action after
  * previously blocking it with midori_browser_block_action().
@@ -7221,7 +7221,7 @@ midori_browser_unblock_action (MidoriBrowser* browser,
  * by the browser. It allows obtaining individual
  * actions and adding new actions.
  *
- * Return value: the action group of the browser
+ * Return value: (transfer none): the action group of the browser
  *
  * Since: 0.1.4
  **/
@@ -7342,23 +7342,23 @@ midori_browser_set_current_item (MidoriBrowser* browser,
 /**
  * midori_browser_get_nth_tab:
  * @browser: a #MidoriBrowser
- * @page: the index of a tab
+ * @n: the index of a tab
  *
- * Retrieves the tab at the position @page.
+ * Retrieves the tab at the position @n.
  *
  * If there is no page present at all, %NULL is returned.
  *
- * Return value: the selected page, or -1
+ * Return value: (type MidoriTab) (transfer none): the selected page, or %NULL
  *
  * Since: 0.1.9
  **/
 GtkWidget*
 midori_browser_get_nth_tab (MidoriBrowser* browser,
-                            gint           page)
+                            gint           n)
 {
     g_return_val_if_fail (MIDORI_IS_BROWSER (browser), NULL);
 
-    return (GtkWidget*)midori_notebook_get_nth_tab (MIDORI_NOTEBOOK (browser->notebook), page);
+    return (GtkWidget*)midori_notebook_get_nth_tab (MIDORI_NOTEBOOK (browser->notebook), n);
 }
 
 /**
@@ -7389,7 +7389,7 @@ midori_browser_set_current_tab (MidoriBrowser* browser,
 }
 
 /**
- * midori_browser_get_tab:
+ * midori_browser_get_current_tab:
  * @browser: a #MidoriBrowser
  *
  * Retrieves the currently selected tab.
@@ -7398,7 +7398,7 @@ midori_browser_set_current_tab (MidoriBrowser* browser,
  *
  * See also midori_browser_get_current_page().
  *
- * Return value: the selected tab, or %NULL
+ * Return value: (transfer none): the selected tab, or %NULL
  *
  * Since: 0.2.6
  **/
@@ -7416,7 +7416,7 @@ midori_browser_get_current_tab (MidoriBrowser* browser)
  *
  * Retrieves the tabs as a list.
  *
- * Return value: a newly allocated #GList of #MidoriView
+ * Return value: (element-type MidoriView) (transfer container): the browser's tabs
  *
  * Since: 0.2.5
  **/
@@ -7435,7 +7435,7 @@ midori_browser_get_tabs (MidoriBrowser* browser)
  * Retrieves a proxy array representing the respective proxy items.
  * The array is updated automatically.
  *
- * Return value: the proxy #KatzeArray
+ * Return value: (transfer none): the proxy #KatzeArray
  **/
 KatzeArray*
 midori_browser_get_proxy_array (MidoriBrowser* browser)
@@ -7451,7 +7451,7 @@ midori_browser_get_proxy_array (MidoriBrowser* browser)
  *
  * Determines the browser appropriate for the specified widget.
  *
- * Return value: a #MidoriBrowser
+ * Return value: (transfer none): a #MidoriBrowser, or %NULL
  *
  * Since 0.1.7
  **/
diff --git a/midori/midori-extension.c b/midori/midori-extension.c
index 87f01259..ab6f6b63 100644
--- a/midori/midori-extension.c
+++ b/midori/midori-extension.c
@@ -581,6 +581,17 @@ midori_extension_load_from_folder (MidoriApp* app,
     g_free (extension_path);
 }
 
+/**
+ * midori_extension_load_from_file:
+ * @extension_path: the path to use for the extension's data files
+ * @filename: the path to the extension's module file
+ * @activate: whether to activate the extension
+ * @test: whether to run the extension's tests
+ *
+ * Load an extension from a file.
+ *
+ * Return value: (transfer none): the loaded extension, or %NULL
+ **/
 GObject*
 midori_extension_load_from_file (const gchar* extension_path,
                                  const gchar* filename,
@@ -640,6 +651,17 @@ midori_extension_load_from_file (const gchar* extension_path,
     return extension;
 }
 
+/**
+ * midori_extension_activate_gracefully:
+ * @app: the #MidoriApp for which to load the extension
+ * @extension_path: the path to use for the extension's data files
+ * @filename: the path to the extension's module file
+ * @activate: whether to activate the extension
+ *
+ * Load an extension into the context of a #MidoriApp.
+ *
+ * Return value: (transfer none): the loaded extension, or %NULL
+ **/
 GObject*
 midori_extension_activate_gracefully (MidoriApp*   app,
                                       const gchar* extension_path,
@@ -826,7 +848,7 @@ midori_extension_deactivate (MidoriExtension* extension)
  * Retrieves the #MidoriApp the extension belongs to. The
  * extension has to be active.
  *
- * Return value: the #MidoriApp instance
+ * Return value: (transfer none): the #MidoriApp instance
  *
  * Since 0.1.6
  **/
@@ -1174,8 +1196,8 @@ midori_extension_install_string_list (MidoriExtension* extension,
  *
  * Retrieves the value of the specified setting.
  *
- * Return value: a newly allocated NULL-terminated list of strings,
- *     should be freed with g_strfreev()
+ * Return value: (transfer full) (array zero-terminated=1): the list of
+ *     strings, NULL-terminated and to be freed with g_strfreev()
  *
  * Since: 0.1.7
  **/
diff --git a/midori/midori-locationaction.c b/midori/midori-locationaction.c
index b03a3739..db64b953 100644
--- a/midori/midori-locationaction.c
+++ b/midori/midori-locationaction.c
@@ -1812,7 +1812,7 @@ midori_location_action_set_progress (MidoriLocationAction* location_action,
 /**
  * midori_location_action_set_secondary_icon:
  * @location_action: a #MidoriLocationAction
- * @icon: a stock ID, or an icon name
+ * @stock_id: a stock ID, or an icon name
  *
  * Sets the secondary, ie right hand side icon.
  *
diff --git a/midori/midori-panel.c b/midori/midori-panel.c
index 10e3b20a..09cfc7e7 100644
--- a/midori/midori-panel.c
+++ b/midori/midori-panel.c
@@ -443,7 +443,7 @@ midori_panel_get_property (GObject*    object,
  *
  * Creates a new empty panel.
  *
- * Return value: a new #MidoriPanel
+ * Return value: (transfer full): a new #MidoriPanel
  **/
 GtkWidget*
 midori_panel_new (void)
@@ -552,9 +552,6 @@ midori_panel_action_activate_cb (GtkRadioAction* action,
  * midori_panel_append_page:
  * @panel: a #MidoriPanel
  * @viewable: a viewable widget
- * @toolbar: a toolbar widget, or %NULL
- * @stock_id: a stock ID
- * @label: a string to use as the label
  *
  * Appends a new page to the panel. If @toolbar is specified it will
  * be packed above @viewable.
@@ -713,7 +710,7 @@ _midori_panel_child_for_scrolled (MidoriPanel* panel,
  *
  * If @panel has no children, %NULL is returned.
  *
- * Return value: the child widget of the new page, or %NULL
+ * Return value: (transfer none): the child widget of the new page, or %NULL
  **/
 GtkWidget*
 midori_panel_get_nth_page (MidoriPanel* panel,
diff --git a/midori/midori-preferences.c b/midori/midori-preferences.c
index 144cef7e..7e5d0c13 100644
--- a/midori/midori-preferences.c
+++ b/midori/midori-preferences.c
@@ -140,7 +140,7 @@ midori_preferences_get_property (GObject*    object,
  *
  * Since 0.1.2 @parent may be %NULL.
  *
- * Return value: a new #MidoriPreferences
+ * Return value: (transfer full): a new #MidoriPreferences
  **/
 GtkWidget*
 midori_preferences_new (GtkWindow*         parent,
diff --git a/midori/midori-privatedata.c b/midori/midori-privatedata.c
index 97b775e6..302493ab 100644
--- a/midori/midori-privatedata.c
+++ b/midori/midori-privatedata.c
@@ -96,7 +96,11 @@ midori_private_data_clear_on_quit_toggled_cb (GtkToggleButton*   button,
 }
 
 /**
+ * midori_private_data_dialog_is_empty:
+ * @dialog: the dialog
+ *
  * The dialog is "empty" when none of the relevant checkboxes are activated.
+ *
  * This function returns true if the dialog is empty.
  **/
 static bool
@@ -131,8 +135,11 @@ midori_private_data_dialog_is_empty (GtkDialog* dialog)
 }
 
 /**
+ * midori_private_data_clear_button_check_sensitive:
+ * @dialog: the dialog to clear
+ * 
  * When called, sets the sensitivity of the clear private data button depending
- * on whether the dialog is empty (see: midori_private_data_dialog_is_empty)
+ * on whether the dialog is empty (see: midori_private_data_dialog_is_empty())
  **/
 static void
 midori_private_data_clear_button_check_sensitive (GtkDialog* dialog)
@@ -153,6 +160,15 @@ midori_private_data_checkbox_toggled_cb (GtkToggleButton*   button,
     midori_private_data_clear_button_check_sensitive (GTK_DIALOG (dialog));
 }
 
+/**
+ * midori_private_data_get_dialog:
+ * @browser: the browser for which to create a dialog
+ *
+ * Shows a dialog for the user to configure private data settings 
+ * and clear some items.
+ *
+ * Return value: (transfer full): the dialog
+ **/
 GtkWidget*
 midori_private_data_get_dialog (MidoriBrowser* browser)
 {
@@ -419,12 +435,14 @@ midori_private_data_on_quit (MidoriWebSettings* settings)
  * midori_private_data_register_item:
  * @name: the name of the privacy item
  * @label: a user visible, localized label
- * @clear: a callback clearing data
+ * @clear: (scope async): a callback clearing data
  *
  * Registers an item to clear data, either via the
  * Clear Private Data dialogue or when Midori quits.
  *
- * Return value: a #GList if all arguments are %NULL
+ * Return value: (element-type MidoriPrivateDataItem) (transfer none):
+ *     a #GList of all previously-registered items if all arguments are
+ *     given as %NULL, %NULL otherwise
  **/
 GList*
 midori_private_data_register_item (const gchar* name,
diff --git a/midori/midori-searchaction.c b/midori/midori-searchaction.c
index 605590cd..705be760 100644
--- a/midori/midori-searchaction.c
+++ b/midori/midori-searchaction.c
@@ -1387,7 +1387,7 @@ midori_search_action_treeview_destroy_cb (GtkWidget*          treeview,
  * the very same dialog until it is destroyed, in which case
  * a new dialog is created.
  *
- * Return value: a #GtkDialog
+ * Return value: (transfer none): a #GtkDialog
  **/
 GtkWidget*
 midori_search_action_get_dialog (MidoriSearchAction* search_action)
diff --git a/midori/midori-view.c b/midori/midori-view.c
index d0e097ae..fbcb01ce 100644
--- a/midori/midori-view.c
+++ b/midori/midori-view.c
@@ -924,7 +924,7 @@ midori_view_infobar_response_cb (GtkWidget* infobar,
  * @view: a #MidoriView
  * @message_type: a #GtkMessageType
  * @message: a message string
- * @response_cb: a response callback
+ * @response_cb: (scope async): a response callback
  * @user_data: user data passed to the callback
  * @first_button_text: button text or stock ID
  * @...: first response ID, then more text - response ID pairs
@@ -933,7 +933,7 @@ midori_view_infobar_response_cb (GtkWidget* infobar,
  * button invokes the specified callback. The infobar is
  * automatically destroyed if the location changes or reloads.
  *
- * Return value: an infobar widget
+ * Return value: (transfer none): an infobar widget
  *
  * Since: 0.2.9
  **/
@@ -3255,7 +3255,7 @@ _midori_view_set_settings (MidoriView*        view,
  * Creates a new view with the specified parameters that
  * is visible by default.
  *
- * Return value: a new #MidoriView
+ * Return value: (transfer full): a new #MidoriView
  *
  * Since: 0.3.0
  * Deprecated: 0.4.3
@@ -3279,7 +3279,7 @@ midori_view_new_with_title (const gchar*       title,
  *
  * Creates a new view from an item that is visible by default.
  *
- * Return value: a new #MidoriView
+ * Return value: (transfer full): a new #MidoriView
  *
  * Since: 0.4.3
  * Deprecated: 0.5.8: Use midori_view_new_from_view instead.
@@ -3316,7 +3316,7 @@ midori_view_new_with_item (KatzeItem*         item,
  *
  * Usually @settings should be passed from an existing view or browser.
  *
- * Return value: a new #MidoriView
+ * Return value: (transfer full): a new #MidoriView
  *
  * Since: 0.5.8
  **/
@@ -4023,7 +4023,7 @@ midori_view_is_blank (MidoriView*  view)
  *
  * The returned icon is owned by the @view and must not be modified.
  *
- * Return value: a #GdkPixbuf, or %NULL
+ * Return value: (transfer none): a #GdkPixbuf, or %NULL
  **/
 GdkPixbuf*
 midori_view_get_icon (MidoriView* view)
@@ -4205,7 +4205,7 @@ midori_view_get_selected_text (MidoriView* view)
  *
  * The menu item is valid until it is removed from its container.
  *
- * Return value: the proxy #GtkMenuItem
+ * Return value: (transfer none): the proxy #GtkMenuItem
  **/
 GtkWidget*
 midori_view_get_proxy_menu_item (MidoriView* view)
@@ -4228,6 +4228,15 @@ midori_view_get_proxy_menu_item (MidoriView* view)
     return view->menu_item;
 }
 
+/**
+ * midori_view_duplicate
+ * @view: a #MidoriView
+ *
+ * Create a new #MidoriView from an existing one by using
+ * the item of the old view.
+ *
+ * Return value: (transfer full): the new #MidoriView
+ **/
 GtkWidget*
 midori_view_duplicate (MidoriView* view)
 {
@@ -4247,7 +4256,7 @@ midori_view_duplicate (MidoriView* view)
  * Retrieves a menu that is typically shown when right-clicking
  * a tab label or equivalent representation.
  *
- * Return value: a #GtkMenu
+ * Return value: (transfer full): a #GtkMenu
  *
  * Since: 0.1.8
  * Deprecated: 0.5.7: Use MidoriNotebook API instead.
@@ -4271,7 +4280,7 @@ midori_view_get_tab_menu (MidoriView* view)
  * Retrieves a proxy tab label that is typically used when
  * adding the view to a notebook.
  *
- * Return value: the proxy #GtkEventBox
+ * Return value: (transfer none): the proxy #GtkEventBox
  *
  * Deprecated: 0.5.7: Don't use this label.
  **/
@@ -4336,7 +4345,7 @@ midori_view_item_meta_data_changed (KatzeItem*   item,
  *
  * The item reflects changes to title (name), URI and MIME type (mime-type).
  *
- * Return value: the proxy #KatzeItem
+ * Return value: (transfer none): the proxy #KatzeItem
  **/
 KatzeItem*
 midori_view_get_proxy_item (MidoriView* view)
@@ -4920,7 +4929,7 @@ midori_view_execute_script (MidoriView*  view,
  * If width and height are negative, the resulting
  * image is going to be optimized for speed.
  *
- * Returns: a newly allocated #GdkPixbuf
+ * Returns: (transfer full): a newly allocated #GdkPixbuf
  *
  * Since: 0.2.1
  * Deprecated: 0.5.4
@@ -4939,7 +4948,7 @@ midori_view_get_snapshot (MidoriView* view,
  * midori_view_get_web_view
  * @view: a #MidoriView
  *
- * Returns: The #WebKitWebView for this view
+ * Returns: (transfer none): The #WebKitWebView for this view
  *
  * Since: 0.2.5
  * Deprecated: 0.4.8: Use midori_tab_get_web_view() instead.
@@ -4954,11 +4963,11 @@ midori_view_get_web_view        (MidoriView*        view)
 
 /**
  * midori_view_get_for_widget:
- * @widget: a #GtkWidget
+ * @web_view: a #GtkWidget of type #WebKitWebView
  *
- * Determines the view appropriate for the specified widget.
+ * Determines the MidoriView for the specified #WebkitWebView widget.
  *
- * Return value: a #MidoriView
+ * Return value: (transfer none): a #MidoriView, or %NULL
  *
  * Since 0.4.5
  **/
diff --git a/midori/midori-websettings.c b/midori/midori-websettings.c
index e420611e..dbdb27f7 100644
--- a/midori/midori-websettings.c
+++ b/midori/midori-websettings.c
@@ -1525,7 +1525,7 @@ midori_settings_new_full (gchar*** extensions)
 /**
  * midori_settings_save_to_file:
  * @settings: a MidoriWebSettings instance to save
- * @app: (type Midori.Application) (allow-none): a MidoriApplication instance
+ * @app: (type MidoriApp) (allow-none): a MidoriApp instance
  * @filename: the filename into which to save settings
  * @error: (out) (allow-none): return location for a GError, or %NULL
  *