docs: ephy-location-action

Bug #503852

6 files changed, 93 insertions, 15 deletions

diff --git a/doc/reference/Makefile.am b/doc/reference/Makefile.am
index 26d4f6402..fe7dfef5c 100644
--- a/doc/reference/Makefile.am
+++ b/doc/reference/Makefile.am
@@ -89,7 +89,6 @@ IGNORE_HFILES = \
 	ephy-favorites-menu.h \
 	ephy-go-action.h \
 	ephy-history-window.h \
-	ephy-location-action.h \
 	ephy-navigation-action.h \
 	ephy-notebook.h \
 	ephy-tabs-menu.h \
diff --git a/doc/reference/epiphany-docs.sgml b/doc/reference/epiphany-docs.sgml
index 97acb71f6..e65406f33 100644
--- a/doc/reference/epiphany-docs.sgml
+++ b/doc/reference/epiphany-docs.sgml
@@ -8,6 +8,7 @@
 
   <chapter>
     <title>Epiphany</title>
+    <xi:include href="xml/ephy-location-action.xml"/>
     <xi:include href="xml/ephy-statusbar.xml"/>
     <xi:include href="xml/ephy-toolbar.xml"/>
     <xi:include href="xml/ephy-window.xml"/>
diff --git a/doc/reference/epiphany-sections.txt b/doc/reference/epiphany-sections.txt
index 1fe73f76a..3b0b7b081 100644
--- a/doc/reference/epiphany-sections.txt
+++ b/doc/reference/epiphany-sections.txt
@@ -96,6 +96,14 @@ ephy_zoom_control_get_zoom_level
 </SECTION>
 
 <SECTION>
+<FILE>ephy-location-action</FILE>
+<TITLE>EphyLocationAction</TITLE>
+EphyLocationAction
+ephy_location_action_get_address
+ephy_location_action_set_address
+</SECTION>
+
+<SECTION>
 <FILE>ephy-statusbar</FILE>
 <TITLE>EphyStatusbar</TITLE>
 EphyStatusbar
diff --git a/doc/reference/epiphany.types b/doc/reference/epiphany.types
index a710225a1..2bea7ae29 100644
--- a/doc/reference/epiphany.types
+++ b/doc/reference/epiphany.types
@@ -15,10 +15,12 @@ ephy_tree_model_sort_get_type
 ephy_zoom_action_get_type
 ephy_zoom_control_get_type
 
+#include <ephy-location-action.h>
 #include <ephy-statusbar.h>
 #include <ephy-toolbar.h>
 #include <ephy-window.h>
 
+ephy_location_action_get_type
 ephy_statusbar_get_type
 ephy_toolbar_get_type
 ephy_window_get_type
diff --git a/lib/widgets/ephy-location-entry.c b/lib/widgets/ephy-location-entry.c
index e8fdcee76..009d5f89f 100644
--- a/lib/widgets/ephy-location-entry.c
+++ b/lib/widgets/ephy-location-entry.c
@@ -1304,13 +1304,10 @@ ephy_location_entry_set_completion (EphyLocationEntry *entry,
 /**
  * ephy_location_entry_set_location:
  * @entry: an #EphyLocationEntry widget
- * @address: the address to be set as the current location
- * @typed_address: the address to be shown in the location entry or NULL
- *
- * Sets the current address of @entry to @address, alternatively a
- * @typed_address can be used to determine the text to be displayed in the
- * location entry.
+ * @address: current location address
+ * @typed_address: address shown in the location entry
  *
+ * Sets the current address of @entry to @address or @typed_address if given.
  **/
 void
 ephy_location_entry_set_location (EphyLocationEntry *entry,
diff --git a/src/ephy-location-action.c b/src/ephy-location-action.c
index 0a4ab396e..baf137c49 100644
--- a/src/ephy-location-action.c
+++ b/src/ephy-location-action.c
@@ -34,6 +34,14 @@
 #include <gtk/gtk.h>
 
 #include <string.h>
+
+/**
+ * SECTION:ephy-location-action
+ * @short_description: An #EphyLinkAction implementation
+ *
+ * #EphyLocationAction handles navigation together with #EphyLocationEntry
+ */
+
 #define EPHY_LOCATION_ACTION_GET_PRIVATE(object)(G_TYPE_INSTANCE_GET_PRIVATE ((object), EPHY_TYPE_LOCATION_ACTION, EphyLocationActionPrivate))
 
 struct _EphyLocationActionPrivate
@@ -655,6 +663,12 @@ ephy_location_action_class_init (EphyLocationActionClass *class)
 	action_class->connect_proxy = connect_proxy;
 	action_class->disconnect_proxy = disconnect_proxy;
 
+	/**
+	* EphyLocationAction::lock-clicked:
+	*
+	* Emitted when the user clicks on the security icon of the internal
+	* #EphyLocationEntry.
+	*/
 	signals[LOCK_CLICKED] = g_signal_new (
 		"lock-clicked",
 		EPHY_TYPE_LOCATION_ACTION,
@@ -665,66 +679,107 @@ ephy_location_action_class_init (EphyLocationActionClass *class)
 		G_TYPE_NONE,
 		0);
 
+	/**
+	* EphyLocationAction:address:
+	*
+	* The address of the current location.
+	*/
 	g_object_class_install_property (object_class,
 					 PROP_ADDRESS,
 					 g_param_spec_string ("address",
 							      "Address",
-							      "The address",
+							      "The address of the current location",
 							      "",
 							      G_PARAM_READWRITE | G_PARAM_STATIC_NAME | G_PARAM_STATIC_NICK | G_PARAM_STATIC_BLURB));
+
+	/**
+	* EphyLocationAction:editable:
+	*
+	* Whether the location bar entry can be edited.
+	*/
 	g_object_class_install_property (object_class,
 					 PROP_EDITABLE,
 					 g_param_spec_boolean ("editable",
 							       "Editable",
-							       "Editable",
+							       "Whether the location bar entry can be edited",
 							       TRUE,
 							       G_PARAM_READWRITE | G_PARAM_STATIC_NAME | G_PARAM_STATIC_NICK | G_PARAM_STATIC_BLURB));
 
+	/**
+	* EphyLocationAction:icon:
+	*
+	* The icon corresponding to the current location.
+	*/
 	g_object_class_install_property (object_class,
 					 PROP_ICON,
 					 g_param_spec_object ("icon",
 							      "Icon",
-							      "The icon",
+							      "The icon corresponding to the current location",
 							      GDK_TYPE_PIXBUF,
 							      G_PARAM_READWRITE | G_PARAM_STATIC_NAME | G_PARAM_STATIC_NICK | G_PARAM_STATIC_BLURB));
 
+	/**
+	* EphyLocationAction:lock-stock-id:
+	*
+	* Stock id of the security icon.
+	*/
 	g_object_class_install_property (object_class,
 					 PROP_LOCK_STOCK,
 					 g_param_spec_string  ("lock-stock-id",
 							       "Lock Stock ID",
-							       "Lock Stock ID",
+							       "Stock id of the security icon",
 							       NULL,
 							       G_PARAM_READWRITE | G_PARAM_STATIC_NAME | G_PARAM_STATIC_NICK | G_PARAM_STATIC_BLURB));
 
+	/**
+	* EphyLocationAction:lock-tooltip:
+	*
+	* Tooltip for the security icon.
+	*/
 	g_object_class_install_property (object_class,
 					 PROP_LOCK_TOOLTIP,
 					 g_param_spec_string  ("lock-tooltip",
 							       "Lock Tooltip",
-							       "The icon",
+							       "Tooltip for the security icon",
 							       NULL,
 							       G_PARAM_READWRITE | G_PARAM_STATIC_NAME | G_PARAM_STATIC_NICK | G_PARAM_STATIC_BLURB));
 
+	/**
+	* EphyLocationAction:secure:
+	*
+	* Whether the current page is loaded over a secure connection.
+	*/
 	g_object_class_install_property (object_class,
 					 PROP_SECURE,
 					 g_param_spec_boolean ("secure",
 							       "Secure",
-							       "Secure",
+							       "Whether the current page is loaded over a secure connection",
 							       FALSE,
 							       G_PARAM_READWRITE | G_PARAM_STATIC_NAME | G_PARAM_STATIC_NICK | G_PARAM_STATIC_BLURB));
 
+	/**
+	* EphyLocationAction:show-lock:
+	*
+	* If we should show the security icon.
+	*/
 	g_object_class_install_property (object_class,
 					 PROP_SHOW_LOCK,
 					 g_param_spec_boolean ("show-lock",
 							       "Show Lock",
-							       "Show Lock",
+							       "If we should show the security icon",
 							       FALSE,
 							       G_PARAM_READWRITE | G_PARAM_STATIC_NAME | G_PARAM_STATIC_NICK | G_PARAM_STATIC_BLURB));
 
+	/**
+	* EphyLocationAction:window:
+	*
+	* The parent window.
+	*/
 	g_object_class_install_property (object_class,
 					 PROP_WINDOW,
 					 g_param_spec_object ("window",
 							      "Window",
-							      "The navigation window",
+							      "The parent window",
 							      G_TYPE_OBJECT,
 							      G_PARAM_WRITABLE | G_PARAM_STATIC_NAME | G_PARAM_STATIC_NICK | G_PARAM_STATIC_BLURB |
 							      G_PARAM_CONSTRUCT_ONLY));
@@ -886,6 +941,14 @@ ephy_location_action_finalize (GObject *object)
 	G_OBJECT_CLASS (ephy_location_action_parent_class)->finalize (object);
 }
 
+/**
+ * ephy_location_action_get_address:
+ * @action: an #EphyLocationAction
+ *
+ * Retrieves the currently loaded address.
+ *
+ * Returns: the current address
+ **/
 const char *
 ephy_location_action_get_address (EphyLocationAction *action)
 {
@@ -894,6 +957,14 @@ ephy_location_action_get_address (EphyLocationAction *action)
 	return action->priv->address;
 }
 
+/**
+ * ephy_location_action_set_address:
+ * @action: an #EphyLocationAction
+ * @address: the current address
+ * @typed_address: address typed by the user
+ *
+ * Sets the @address and @typed_address in @action.
+ **/
 void
 ephy_location_action_set_address (EphyLocationAction *action,
 				  const char *address,