introspection: fix wrong and missing annotations

Bug #636790

11 files changed, 104 insertions, 35 deletions

diff --git a/embed/ephy-embed-container.c b/embed/ephy-embed-container.c
index 75ca72e78..7c9e5ed72 100644
--- a/embed/ephy-embed-container.c
+++ b/embed/ephy-embed-container.c
@@ -142,7 +142,7 @@ ephy_embed_container_remove_child (EphyEmbedContainer *container,
 
 /**
  * ephy_embed_container_get_active_child:
- * @window: an #EphyEmbedContainer
+ * @container: an #EphyEmbedContainer
  *
  * Returns @container's active #EphyEmbed.
  *
diff --git a/embed/ephy-embed-shell.c b/embed/ephy-embed-shell.c
index d8650a50b..3fcf7ee82 100644
--- a/embed/ephy-embed-shell.c
+++ b/embed/ephy-embed-shell.c
@@ -173,6 +173,7 @@ ephy_embed_shell_get_favicon_cache (EphyEmbedShell *shell)
 
 /**
  * ephy_embed_shell_get_global_history:
+ * @shell: the #EphyEmbedShell
  *
  * Return value: (transfer none):
  **/
@@ -191,6 +192,7 @@ ephy_embed_shell_get_global_history (EphyEmbedShell *shell)
 
 /**
  * ephy_embed_shell_get_downloader_view:
+ * @shell: the #EphyEmbedShell
  *
  * Return value: (transfer none):
  **/
@@ -214,6 +216,7 @@ ephy_embed_shell_get_downloader_view (EphyEmbedShell *shell)
 
 /**
  * ephy_embed_shell_get_downloader_view_nocreate:
+ * @shell: the #EphyEmbedShell
  *
  * Return value: (transfer none):
  **/
@@ -271,6 +274,7 @@ impl_get_embed_single (EphyEmbedShell *shell)
 
 /**
  * ephy_embed_shell_get_embed_single:
+ * @shell: the #EphyEmbedShell
  *
  * Return value: (transfer none):
  **/
@@ -284,6 +288,7 @@ ephy_embed_shell_get_embed_single (EphyEmbedShell *shell)
 
 /**
  * ephy_embed_shell_get_encodings:
+ * @shell: the #EphyEmbedShell
  *
  * Return value: (transfer none):
  **/
@@ -328,7 +333,7 @@ ephy_embed_shell_class_init (EphyEmbedShellClass *klass)
 
 /**
  * EphyEmbed::prepare-close:
- * @shell:
+ * @shell: the #EphyEmbedShell
  * 
  * The ::prepare-close signal is emitted when epiphany is preparing to
  * quit on command from the session manager. You can use it when you need
@@ -485,6 +490,14 @@ ephy_embed_shell_get_page_setup	(EphyEmbedShell *shell)
 	return priv->page_setup;
 }
 
+/**
+ * ephy_embed_shell_set_print_gettings:
+ * @shell: the #EphyEmbedShell
+ * @settings: the new #GtkPrintSettings object
+ *
+ * Sets the global #GtkPrintSettings object.
+ *
+ **/
 void
 ephy_embed_shell_set_print_settings (EphyEmbedShell *shell,
 				     GtkPrintSettings *settings)
@@ -513,9 +526,12 @@ ephy_embed_shell_set_print_settings (EphyEmbedShell *shell,
 }
 
 /**
- * ephy_embed_shell_get_print_gettings:
+ * ephy_embed_shell_get_print_settings:
+ * @shell: the #EphyEmbedShell
  *
- * Return value: (transfer none):
+ * Gets the global #GtkPrintSettings object.
+ *
+ * Returns: (transfer none): a #GtkPrintSettings object
  **/
 GtkPrintSettings *
 ephy_embed_shell_get_print_settings (EphyEmbedShell *shell)
@@ -534,8 +550,8 @@ ephy_embed_shell_get_print_settings (EphyEmbedShell *shell)
 		priv->print_settings = gtk_print_settings_new_from_file (path, &error);
 		g_free (path);
 
-		/* Note: the gtk print settings file format is the same as our legacy one,
-		 * so no need to migrate here.
+		/* Note: the gtk print settings file format is the same as our
+		 * legacy one, so no need to migrate here.
 		 */
 
 		if (priv->print_settings == NULL)
diff --git a/embed/ephy-embed-shell.h b/embed/ephy-embed-shell.h
index ef10c2acc..c58df978c 100644
--- a/embed/ephy-embed-shell.h
+++ b/embed/ephy-embed-shell.h
@@ -65,7 +65,7 @@ GType		   ephy_embed_shell_get_type		(void);
 
 EphyEmbedShell	  *ephy_embed_shell_get_default		(void);
 
-GObject		  *ephy_embed_shell_get_favicon_cache	(EphyEmbedShell *ges);
+GObject		  *ephy_embed_shell_get_favicon_cache	(EphyEmbedShell *shell);
 
 GObject		  *ephy_embed_shell_get_global_history	(EphyEmbedShell *shell);
 
diff --git a/embed/ephy-embed-single.c b/embed/ephy-embed-single.c
index 94a18b889..afab4e1cb 100644
--- a/embed/ephy-embed-single.c
+++ b/embed/ephy-embed-single.c
@@ -293,14 +293,13 @@ ephy_embed_single_class_init (EphyEmbedSingleClass *klass)
 
   /**
    * EphyEmbedSingle::new-window:
-   * @single:
    * @parent_embed: the #EphyEmbed requesting the new window, or %NULL
    * @mask: a #EphyEmbedChrome
    *
    * The ::new_window signal is emitted when a new window needs to be opened.
    * For example, when a JavaScript popup window was opened.
    *
-   * Return a new #EphyEmbed.
+   * Returns: (transfer none): a new #EphyEmbed.
    **/
   g_signal_new ("new-window",
                 EPHY_TYPE_EMBED_SINGLE,
@@ -620,11 +619,11 @@ ephy_embed_single_get_network_status (EphyEmbedSingle *single)
  * method and arguments: <code>window.open(&quot;@address&quot;,
  * &quot;_blank&quot;, &quot;@features&quot;);</code>.
  * 
- * Returns: the new embed. This is either a #EphyEmbed, or, when @features specified
- * "chrome", a #GtkMozEmbed.
+ * Returns: (transfer none): the new embed. This is either a #EphyEmbed, or,
+ * when @features specified "chrome", a #GtkMozEmbed.
  *
- * NOTE: Use ephy_shell_new_tab() unless this handling of the @features string is
- * required.
+ * NOTE: Use ephy_shell_new_tab() unless this handling of the @features string
+ * is required.
  */
 GtkWidget *
 ephy_embed_single_open_window (EphyEmbedSingle *single,
@@ -648,8 +647,8 @@ ephy_embed_single_open_window (EphyEmbedSingle *single,
  * The #EphyEmbedSingleFormAuthData structs and the #GSList are owned
  * by @single and should not be freed by the user.
  * 
- * Returns: #GSList with the possible auto-fills for the forms in
- * @uri, or %NULL
+ * Returns: (transfer none): #GSList with the possible auto-fills for the forms
+ * in @uri, or %NULL
  **/
 GSList *
 ephy_embed_single_get_form_auth (EphyEmbedSingle *single,
diff --git a/embed/ephy-favicon-cache.c b/embed/ephy-favicon-cache.c
index 23e528b78..e4fc82ec4 100644
--- a/embed/ephy-favicon-cache.c
+++ b/embed/ephy-favicon-cache.c
@@ -564,14 +564,14 @@ ephy_favicon_cache_download (EphyFaviconCache *cache,
 }
 
 /**
- * ephy_favicons_cache_get:
+ * ephy_favicon_cache_get:
  * @cache: an #EphyFaviconCache
  * @url: the URL of the icon to retrieve
  * 
  * Note: This will always return %NULL for non-http URLs.
  * 
- * Return value: the site icon at @url as a #GdkPixbuf, or %NULL if
- * if could not be retrieved. Unref when you don't need it anymore.
+ * Return value: (transfer full): the site icon at @url as a #GdkPixbuf, or
+ * %NULL if if could not be retrieved. Unref when you don't need it anymore.
  */
 GdkPixbuf *
 ephy_favicon_cache_get (EphyFaviconCache *cache,
diff --git a/embed/ephy-permission-manager.c b/embed/ephy-permission-manager.c
index 9ae054c8d..2deaf94b9 100644
--- a/embed/ephy-permission-manager.c
+++ b/embed/ephy-permission-manager.c
@@ -44,7 +44,7 @@ ephy_permission_info_get_type (void)
  * ephy_permission_info_new:
  * @host: a host name
  * @type: an #EphyPermissionType
- * @allowed: whether @host should be allowed to do what @type specifies
+ * @permission: whether @host should be allowed to do what @type specifies
  *
  * Return value: the new #EphyPermissionInfo
  **/
@@ -278,7 +278,7 @@ ephy_permission_manager_test_permission (EphyPermissionManager *manager,
 }
 
 /**
- * ephy_permission_manager_list_permission:
+ * ephy_permission_manager_list_permissions:
  * @manager: the #EphyPermissionManager
  * @type: a string to identify the type of the permission
  * 
@@ -286,7 +286,7 @@ ephy_permission_manager_test_permission (EphyPermissionManager *manager,
  * as its own #EphyPermissionInfo. These entries must be freed using
  * ephy_permission_info_free().
  * 
- * Return value: the list of permission database entries
+ * Return value: (transfer none): the list of permission database entries
  **/
 GList *
 ephy_permission_manager_list_permissions (EphyPermissionManager *manager,
diff --git a/embed/ephy-web-view.c b/embed/ephy-web-view.c
index 37fc1f97f..6a0c52f87 100644
--- a/embed/ephy-web-view.c
+++ b/embed/ephy-web-view.c
@@ -3230,8 +3230,8 @@ ephy_web_view_print (EphyWebView *view)
  * "http://www.example.com/dir/subdir/", "http://www.example.com/dir/" and
  * "http://www.example.com/".
  *
- * Return value: a list of URLs higher up in @view's web page's directory
- * hierarchy
+ * Return value: (transfer none): a list of URLs higher up in @view's web
+ * page's directory hierarchy
  **/
 GSList *
 ephy_web_view_get_go_up_list (EphyWebView *view)
diff --git a/lib/ephy-node.c b/lib/ephy-node.c
index 4194705bd..9413074a0 100644
--- a/lib/ephy-node.c
+++ b/lib/ephy-node.c
@@ -1143,6 +1143,14 @@ ephy_node_real_get_child_index (EphyNode *node,
 	return ret;
 }
 
+/**
+ * ephy_node_sort_children:
+ * @node: an #EphyNode
+ * @compare_func: (scope call): function to compare children
+ *
+ * Sorts the children of @node using @compare_func.
+ *
+ **/
 void
 ephy_node_sort_children (EphyNode *node,
 			 GCompareFunc compare_func)
@@ -1353,6 +1361,17 @@ ephy_node_get_previous_child (EphyNode *node,
 	return ret;
 }
 
+/**
+ * ephy_node_signal_connect_object:
+ * @node: an #EphyNode
+ * @type: signal type
+ * @callback: (scope notified): the callback to connect
+ * @object: data to pass to @callback
+ *
+ * Connects a callback function to the @type signal of @node.
+ *
+ * Returns: an identifier for the connected signal
+ **/
 int
 ephy_node_signal_connect_object (EphyNode *node,
 				 EphyNodeSignalType type,
@@ -1414,6 +1433,18 @@ invalidate_matching_signal_data (gpointer key,
 	}
 }
 
+/**
+ * ephy_node_signal_disconnect_object:
+ * @node: an #EphyNode
+ * @type: signal type
+ * @callback: (scope notified): the callback to disconnect
+ * @object: data passed to @callback when it was connected
+ *
+ * Disconnects @callback from @type in @node. @callback is identified by the
+ * @object previously passed in ephy_node_signal_connect_object.
+ *
+ * Returns: the number of signal handlers removed
+ **/
 guint
 ephy_node_signal_disconnect_object (EphyNode *node,
                                     EphyNodeSignalType type,
diff --git a/lib/widgets/ephy-location-entry.c b/lib/widgets/ephy-location-entry.c
index 5b2c9dc0d..9df8fcf9a 100644
--- a/lib/widgets/ephy-location-entry.c
+++ b/lib/widgets/ephy-location-entry.c
@@ -220,7 +220,7 @@ ephy_location_entry_class_init (EphyLocationEntryClass *klass)
 
 	widget_class->style_set = ephy_location_entry_style_set;
 
-    /**
+       /**
 	* EphyLocationEntry::user-changed:
 	* @entry: the object on which the signal is emitted
 	*
@@ -237,7 +237,7 @@ ephy_location_entry_class_init (EphyLocationEntryClass *klass)
 		0,
 		G_TYPE_NONE);
 
-    /**
+       /**
 	* EphyLocationEntry::lock-clicked:
 	* @entry: the object on which the signal is emitted
 	*
@@ -255,14 +255,14 @@ ephy_location_entry_class_init (EphyLocationEntryClass *klass)
 		G_TYPE_NONE,
 		0);
 
-    /**
+       /**
 	* EphyLocationEntry::get-location:
 	* @entry: the object on which the signal is emitted
 	* Returns: the current page address as a string
 	*
-	* For drag and drop purposes, the location bar will request you the real
-	* address of where it is pointing to. The signal handler for this function
-	* should return the address of the currently loaded site.
+	* For drag and drop purposes, the location bar will request you the
+	* real address of where it is pointing to. The signal handler for this
+	* function should return the address of the currently loaded site.
 	*
 	*/
 	signals[GET_LOCATION] = g_signal_new (
@@ -275,14 +275,14 @@ ephy_location_entry_class_init (EphyLocationEntryClass *klass)
 		0,
 		G_TYPE_NONE);
 
-    /**
+       /**
 	* EphyLocationEntry::get-title:
 	* @entry: the object on which the signal is emitted
 	* Returns: the current page title as a string
 	*
-	* For drag and drop purposes, the location bar will request you the title
-	* of where it is pointing to. The signal handler for this function
-	* should return the title of the currently loaded site.
+	* For drag and drop purposes, the location bar will request you the
+	* title of where it is pointing to. The signal handler for this
+	* function should return the title of the currently loaded site.
 	*
 	*/
 	signals[GET_TITLE] = g_signal_new (
diff --git a/src/ephy-link.c b/src/ephy-link.c
index 49faa52ae..988132826 100644
--- a/src/ephy-link.c
+++ b/src/ephy-link.c
@@ -43,6 +43,18 @@ ephy_link_base_init (gpointer g_class)
 
 	if (!initialised)
 	{
+		/**
+		 * EphyLink::open-link:
+		 * @address: the address of @link
+		 * @embed: #EphyEmbed associated with @link
+		 * @flags: flags for @link
+		 *
+		 * The ::open-link signal is emitted when @link is requested to
+		 * open it's associated @address.
+		 *
+		 * Returns: (transfer none): the #EphyEmbed where @address has
+		 * been handled.
+		 **/
 		signals[OPEN_LINK] = g_signal_new
 			("open-link",
 			 EPHY_TYPE_LINK,
@@ -82,6 +94,17 @@ ephy_link_get_type (void)
 	return type;
 }
 
+/**
+ * ephy_link_open:
+ * @link: an #EphyLink object
+ * @address: the address of @link
+ * @embed: #EphyEmbed associated with @link
+ * @flags: flags for @link
+ *
+ * Triggers @link open action.
+ *
+ * Returns: (transfer none): the #EphyEmbed where @link opened.
+ */
 EphyEmbed *
 ephy_link_open (EphyLink *link,
 		const char *address,
diff --git a/src/ephy-toolbar.c b/src/ephy-toolbar.c
index a6edc29c0..65b515872 100644
--- a/src/ephy-toolbar.c
+++ b/src/ephy-toolbar.c
@@ -353,12 +353,12 @@ ephy_toolbar_set_window (EphyToolbar *toolbar,
 /* public functions */
 
 /**
- * ephy_toolbar_get_action_group
+ * ephy_toolbar_get_action_group:
  * @toolbar: an #EphyToolbar widget
  *
  * Gets the #GtkActionGroup for @toolbar.
  *
- * Return value: (transfer none):
+ * Return value: (transfer none): the #GtkActionGroup associated with @toolbar
  **/
 GtkActionGroup *
 ephy_toolbar_get_action_group (EphyToolbar *toolbar)