API documentation

5 files changed, 245 insertions, 53 deletions

diff --git a/doc/plan.xml b/doc/plan.xml
index 18326e01e..c850afa7a 100644
--- a/doc/plan.xml
+++ b/doc/plan.xml
@@ -79,9 +79,14 @@
   </item>

   

   <item>

-    <title>Extensions: Loading/Unloading</title>

+    <title>Extensions Lifecycle</title>

     <description>

-      Dynamic loading/unloading of extensions.

+      Right now the startup process is: &quot;startup -&gt; get session -&gt;

+      get extensions manager -&gt; load extensions -&gt; get session&quot;. We

+      should make the extensions manager load extensions *later*, so that the

+      session is created for them by the time they need it.

+

+      This should pave the way for dynamic loading/unloading of extensions.

     </description>

     <status id="pending"/>

     <responsible email="adamh@densi.com">Adam Hooper</responsible>

diff --git a/doc/reference-howto.txt b/doc/reference-howto.txt
index 743b636aa..66dc14f22 100644
--- a/doc/reference-howto.txt
+++ b/doc/reference-howto.txt
@@ -11,7 +11,7 @@ For example:
  *
  * Resume a crashed session when necessary (interactive)
  *
- * Return value: TRUE if at least a window has been opened
+ * Return value: %TRUE if at least a window has been opened
  **/
 gboolean
 ephy_session_autoresume (EphySession *session)
diff --git a/doc/reference/Makefile.am b/doc/reference/Makefile.am
index 5da5f7d7f..bf39bae09 100644
--- a/doc/reference/Makefile.am
+++ b/doc/reference/Makefile.am
@@ -138,7 +138,6 @@ IGNORE_HFILES = \
 	ephy-tab.h \
 	ephy-tabs-menu.h \
 	ephy-toolbars-model.h \
-	ephy-window.h \
 	language-editor.h \
 	pdm-dialog.h \
 	popup-commands.h \
diff --git a/doc/reference/tmpl/ephy-permission-manager.sgml b/doc/reference/tmpl/ephy-permission-manager.sgml
index 516bfac21..f62bd4de1 100644
--- a/doc/reference/tmpl/ephy-permission-manager.sgml
+++ b/doc/reference/tmpl/ephy-permission-manager.sgml
@@ -1,79 +1,77 @@
 <!-- ##### SECTION Title ##### -->
-ephy-permission-manager
+EphyPermissionManager
 
 <!-- ##### SECTION Short_Description ##### -->
-
+Sets webpages' cookie, image and popup permissions.
 
 <!-- ##### SECTION Long_Description ##### -->
 <para>
-
+The #EphyPermissionManager keeps a list of websites and their permissions. For
+example, the user may want a certain website to display images but block
+cookies and popup windows; this could correspond to three entries in the
+#EphyPermissionManager.
 </para>
-
-<!-- ##### SECTION See_Also ##### -->
 <para>
-
+Use ephy_permission_manager_add() to set permissions for a website,
+ephy_permission_manager_remove() to remove the permissions, and
+ephy_permission_manager_test() to test them. Note that
+ephy_permission_manager_test() may return %EPHY_PERMISSION_DEFAULT, which
+means the caller might need to find the default permission some other way.
 </para>
-
-<!-- ##### MACRO EPHY_PERMISSION_MANAGER_IFACE ##### -->
 <para>
-
+The #EphyPermissionManager stores a list of site-specific permissions, but not
+defaults. For popups, the default permission is determined by the GConf key
+/apps/epiphany/web/allow_popups, which in turn determines Mozilla's
+dom.disable_open_during_load preference. For cookies, the GConf key
+/apps/epiphany/web/cookie_accept determines Mozilla's
+network.cookie.cookieBehavior preference. For images, the default is determined
+by Mozilla's network.image.imageBehavior preference.
 </para>
-
-@k: 
-
-
-<!-- ##### MACRO EPHY_IS_PERMISSION_MANAGER_IFACE ##### -->
 <para>
-
+Though the word &quot;host&quot; is used in many function descriptions, Mozilla
+does not act as one would expect. Always pass a URL to any functions which
+need have a &quot;host&quot; parameter. However, the &quot;host&quot; in an
+#EphyPermissionInfo is a simple DNS hostname.
 </para>
 
-@k: 
-
-
-<!-- ##### MACRO EPHY_TYPE_PERMISSION_INFO ##### -->
+<!-- ##### SECTION See_Also ##### -->
 <para>
 
 </para>
 
+<!-- ##### STRUCT EphyPermissionInfo ##### -->
+<para>
+Details a specific permission of a specific website.
+</para>
 
+@host: The hostname of the website to which this permission applies.
+@type: An #EphyPermissionType.
+@permission: An #EphyPermission (either allow or deny).
 
 <!-- ##### ENUM EphyPermissionType ##### -->
 <para>
-
+Determines what permission we're dealing with.
 </para>
 
 @EPT_COOKIE: 
+	Permission for the website to store cookies on the user's computer.
 @EPT_IMAGE: 
+	Permission for the website to show images to the user.
 @EPT_POPUP: 
+	Permission for the website to open popup windows (using JavaScript).
 
 <!-- ##### ENUM EphyPermission ##### -->
 <para>
-
+Determines whether the website is allowed or denied access.
 </para>
 
 @EPHY_PERMISSION_ALLOWED: 
+	The website is unconditionally allowed to perform the desired action.
 @EPHY_PERMISSION_DENIED: 
+	The website is unconditionally denied to perform the desired action.
 @EPHY_PERMISSION_DEFAULT: 
-
-<!-- ##### FUNCTION ephy_permission_info_new ##### -->
-<para>
-
-</para>
-
-@host: 
-@type: 
-@permission: 
-@Returns: 
-
-
-<!-- ##### FUNCTION ephy_permission_info_copy ##### -->
-<para>
-
-</para>
-
-@info: 
-@Returns: 
-
+	The user has not set a preference for this particular website; the
+	caller should therefore fall back to default settings.
 
 <!-- ##### FUNCTION ephy_permission_info_free ##### -->
 <para>
@@ -83,14 +81,6 @@ ephy-permission-manager
 @info: 
 
 
-<!-- ##### FUNCTION ephy_permission_manager_get_type ##### -->
-<para>
-
-</para>
-
-@Returns: 
-
-
 <!-- ##### FUNCTION ephy_permission_manager_add ##### -->
 <para>
 
diff --git a/doc/reference/tmpl/ephy-window.sgml b/doc/reference/tmpl/ephy-window.sgml
new file mode 100644
index 000000000..391abd920
--- /dev/null
+++ b/doc/reference/tmpl/ephy-window.sgml
@@ -0,0 +1,198 @@
+<!-- ##### SECTION Title ##### -->
+EphyWindow
+
+<!-- ##### SECTION Short_Description ##### -->
+Represents an Epiphany window.
+
+<!-- ##### SECTION Long_Description ##### -->
+<para>
+An #EphyWindow is what the user sees when opening Epiphany. Think of each
+#EphyWindow as a giant container which holds many useful items:
+</para>
+<itemizedlist>
+<listitem>A toolbar, available from ephy_window_get_toolbar().</listitem>
+<listitem>An #EphyStatusbar, available from
+ephy_window_get_statusbar().</listitem>
+<listitem>A #GtkNotebook for holding #EphyTabs. Use ephy_window_get_notebook(),
+ephy_window_get_tabs() and ephy_window_get_active_tab() to reach
+them. Manipulate tabs using ephy_window_add_tab(), ephy_window_remove_tab()
+and ephy_window_jump_to_tab().</listitem>
+</itemizedlist>
+<para>
+You can also perform simple manipulations of an #EphyWindow's active #EphyEmbed.
+These are restricted to ephy_window_set_zoom() and ephy_window_load_url().
+</para>
+
+<!-- ##### SECTION See_Also ##### -->
+<para>
+
+</para>
+
+<!-- ##### STRUCT EphyWindow ##### -->
+<para>
+
+</para>
+
+@ui_merge: The #GtkUIManager this window uses to merge user interfaces
+
+<!-- ##### FUNCTION ephy_window_new ##### -->
+<para>
+
+</para>
+
+@Returns: 
+
+
+<!-- ##### FUNCTION ephy_window_new_with_chrome ##### -->
+<para>
+
+</para>
+
+@chrome: 
+@Returns: 
+
+
+<!-- ##### FUNCTION ephy_window_get_notebook ##### -->
+<para>
+
+</para>
+
+@window: 
+@Returns: 
+
+
+<!-- ##### FUNCTION ephy_window_add_tab ##### -->
+<para>
+
+</para>
+
+@window: 
+@tab: 
+@position: 
+@jump_to: 
+
+
+<!-- ##### FUNCTION ephy_window_remove_tab ##### -->
+<para>
+
+</para>
+
+@window: 
+@tab: 
+
+
+<!-- ##### FUNCTION ephy_window_jump_to_tab ##### -->
+<para>
+
+</para>
+
+@window: 
+@tab: 
+
+
+<!-- ##### FUNCTION ephy_window_get_tabs ##### -->
+<para>
+
+</para>
+
+@window: 
+@Returns: 
+
+
+<!-- ##### FUNCTION ephy_window_get_active_tab ##### -->
+<para>
+
+</para>
+
+@window: 
+@Returns: 
+
+
+<!-- ##### FUNCTION ephy_window_get_active_embed ##### -->
+<para>
+
+</para>
+
+@window: 
+@Returns: 
+
+
+<!-- ##### FUNCTION ephy_window_get_toolbar ##### -->
+<para>
+
+</para>
+
+@window: 
+@Returns: 
+
+
+<!-- ##### FUNCTION ephy_window_get_statusbar ##### -->
+<para>
+
+</para>
+
+@window: 
+@Returns: 
+
+
+<!-- ##### FUNCTION ephy_window_find ##### -->
+<para>
+
+</para>
+
+@window: 
+
+
+<!-- ##### FUNCTION ephy_window_print ##### -->
+<para>
+
+</para>
+
+@window: 
+
+
+<!-- ##### FUNCTION ephy_window_set_print_preview ##### -->
+<para>
+
+</para>
+
+@window: 
+@enabled: 
+
+
+<!-- ##### FUNCTION ephy_window_set_zoom ##### -->
+<para>
+
+</para>
+
+@window: 
+@zoom: 
+
+
+<!-- ##### FUNCTION ephy_window_activate_location ##### -->
+<para>
+
+</para>
+
+@window: 
+
+
+<!-- ##### FUNCTION ephy_window_load_url ##### -->
+<para>
+
+</para>
+
+@window: 
+@url: 
+
+
+<!-- ##### ARG EphyWindow:active-tab ##### -->
+<para>
+
+</para>
+
+<!-- ##### ARG EphyWindow:chrome ##### -->
+<para>
+
+</para>
+