EphyEmbedPersist documentation

8 files changed, 554 insertions, 8 deletions

diff --git a/ChangeLog b/ChangeLog
index e215dfb77..f9c3edc88 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,17 @@
+2004-03-27  Adam Hooper  <adamh@cvs.gnome.org>
+
+	* doc/reference/Makefile.am:
+	* doc/reference/epiphany-docs.sgml:
+	* doc/reference/epiphany-sections.txt:
+	* doc/reference/epiphany.types:
+	* doc/reference/tmpl/ephy-embed-persist.sgml:
+	* embed/ephy-embed-persist.c: (ephy_embed_persist_get_type),
+	(ephy_embed_persist_class_init):
+	* embed/ephy-embed-persist.h:
+
+	Document EphyEmbedPersist. Also, make it an abstract class. Change
+	the return type of ephy_embed_persist_get_type() to long.
+
 2004-03-27  Piers Cornwell  <piers@gnome.org>
 
 	* src/bookmarks/ephy-bookmarks-editor.c: (cmd_bookmarks_import):
diff --git a/doc/reference/Makefile.am b/doc/reference/Makefile.am
index cf981f0b6..0b0df505d 100644
--- a/doc/reference/Makefile.am
+++ b/doc/reference/Makefile.am
@@ -69,7 +69,6 @@ IGNORE_HFILES = \
 	ephy-download.h \
 	ephy-embed-dialog.h \
 	ephy-embed-event.h \
-	ephy-embed-persist.h \
 	ephy-embed-popup-control.h \
 	ephy-embed-prefs.h \
 	ephy-embed-shell.h \
diff --git a/doc/reference/epiphany-docs.sgml b/doc/reference/epiphany-docs.sgml
index aa8abfa73..1d399f151 100644
--- a/doc/reference/epiphany-docs.sgml
+++ b/doc/reference/epiphany-docs.sgml
@@ -13,6 +13,7 @@
     <xi:include href="xml/ephy-tab.xml"/>
     <xi:include href="xml/ephy-embed.xml"/>
     <xi:include href="xml/ephy-embed-single.xml"/>
+    <xi:include href="xml/ephy-embed-persist.xml"/>
   </chapter>
   <chapter>
     <title>Incomplete</title>
diff --git a/doc/reference/epiphany-sections.txt b/doc/reference/epiphany-sections.txt
index 3cb40f04e..398ef5c83 100644
--- a/doc/reference/epiphany-sections.txt
+++ b/doc/reference/epiphany-sections.txt
@@ -150,6 +150,39 @@ EPHY_EMBED_SINGLE_IFACE
 EPHY_IS_EMBED_SINGLE_IFACE
 </SECTION>
 
+<SECTION>
+<FILE>ephy-embed-persist</FILE>
+<TITLE>EphyEmbedPersist</TITLE>
+EmbedPersistFlags
+ephy_embed_persist_set_dest
+ephy_embed_persist_set_embed
+ephy_embed_persist_set_fc_title
+ephy_embed_persist_set_fc_parent
+ephy_embed_persist_set_flags
+ephy_embed_persist_set_max_size
+ephy_embed_persist_set_persist_key
+ephy_embed_persist_set_source
+ephy_embed_persist_get_dest
+ephy_embed_persist_get_embed
+ephy_embed_persist_get_fc_title
+ephy_embed_persist_get_fc_parent
+ephy_embed_persist_get_flags
+ephy_embed_persist_get_max_size
+ephy_embed_persist_get_persist_key
+ephy_embed_persist_get_source
+ephy_embed_persist_save
+ephy_embed_persist_cancel
+ephy_embed_persist_to_string
+<SUBSECTION Standard>
+EPHY_EMBED_PERSIST
+EPHY_IS_EMBED_PERSIST
+EPHY_TYPE_EMBED_PERSIST
+ephy_embed_persist_get_type
+EPHY_EMBED_PERSIST_CLASS
+EPHY_IS_EMBED_PERSIST_CLASS
+EPHY_EMBED_PERSIST_GET_CLASS
+</SECTION>
+
 
 
 
diff --git a/doc/reference/epiphany.types b/doc/reference/epiphany.types
index 098dc3f66..58dd8ba78 100644
--- a/doc/reference/epiphany.types
+++ b/doc/reference/epiphany.types
@@ -30,6 +30,7 @@ ephy_cell_renderer_progress_get_type
 #include <ephy-password-manager.h>
 #include <ephy-permission-manager.h>
 #include <mozilla-embed.h>
+#include <mozilla-embed-persist.h>
 
 ephy_embed_get_type
 downloader_view_get_type
@@ -43,6 +44,7 @@ ephy_cookie_manager_get_type
 ephy_permission_manager_get_type
 ephy_password_manager_get_type
 mozilla_embed_get_type
+mozilla_embed_persist_get_type
 
 #include <ephy-window.h>
 #include <ephy-tab.h>
diff --git a/doc/reference/tmpl/ephy-embed-persist.sgml b/doc/reference/tmpl/ephy-embed-persist.sgml
new file mode 100644
index 000000000..be75437c8
--- /dev/null
+++ b/doc/reference/tmpl/ephy-embed-persist.sgml
@@ -0,0 +1,308 @@
+<!-- ##### SECTION Title ##### -->
+EphyEmbedPersist
+
+<!-- ##### SECTION Short_Description ##### -->
+A class to download files
+
+<!-- ##### SECTION Long_Description ##### -->
+<para>
+An #EphyEmbedPersist is a relatively simple way to save a web page or file to
+disk. It is an abstract class, implemented by #MozillaEmbedPersist.
+</para>
+<para>
+To create an #EphyEmbedPersist, use ephy_embed_factory_new_object(). Next, call
+ephy_embed_persist_set_flags() and ephy_embed_persist_set_embed(). Depending
+on the flags, you may also want to call ephy_embed_persist_set_dest() or
+ephy_embed_persist_set_source(). Finally, call ephy_embed_persist_save() to
+save the file.
+</para>
+<para>
+<example>
+<title>Saving the current web page to disk</title>
+<programlisting>#<![CDATA[include <epiphany/ephy-embed-persist.h>]]>
+#<![CDATA[include <epiphany/ephy-embed.h>
+
+static void
+save_source_completed_cb (EphyEmbedPersist *persist,
+			  gpointer dummy)
+{
+	g_print ("Download to %]]><![CDATA[s complete.\n",
+		 ephy_embed_persist_get_dest (persist));
+}
+
+void
+save_page (EphyEmbed *embed,
+	   const char *filename)
+{
+	EphyEmbedPersist *persist;
+
+	persist = EPHY_EMBED_PERSIST
+		(ephy_embed_factory_new_object ("EphyEmbedPersist"));
+
+	ephy_embed_persist_set_embed (persist, embed);
+	ephy_embed_persist_set_flags (persist, EMBED_PERSIST_NO_VIEW |
+					       EMBED_PERSIST_COPY_PAGE);
+	ephy_embed_persist_set_dest (persist, filename);
+
+	g_signal_connect (persist, "completed",
+			  G_CALLBACK (save_source_completed_cb), NULL);
+	
+	ephy_embed_persist_save (persist);
+
+	g_object_unref (persist);
+}]]>
+</programlisting>
+</example>
+</para>
+
+<!-- ##### SECTION See_Also ##### -->
+<para>
+
+</para>
+
+<!-- ##### ENUM EmbedPersistFlags ##### -->
+<para>
+Determines how the #EphyEmbedPersist should act.
+</para>
+
+@EMBED_PERSIST_COPY_PAGE: If set, download a copy of the page being browsed by
+			  the #EphyEmbedPersist's #EphyEmbed. This should be
+			  specified with ephy_embed_persist_set_embed(). If
+			  unset, ephy_embed_persist_set_source() must have been
+			  called.
+@EMBED_PERSIST_MAINDOC: If set and %EMBED_PERSIST_COPY_PAGE is set, download the
+			#EphyEmbedPersist's #EphyEmbed's page's frameset. If
+			unset, download the currently-focused frame.
+@EMBED_PERSIST_NO_VIEW: If set, do not display this download in the download
+			manager.
+@EMBED_PERSIST_ASK_DESTINATION: If set, display a filechooser dialog. You must
+				call ephy_embed_persist_set_fc_title() and
+				ephy_embed_persist_set_fc_parent() before
+				ephy_embed_persist_save() if this is the case.
+				If unset, use the destination specified with
+				ephy_embed_persist_set_dest().
+
+<!-- ##### FUNCTION ephy_embed_persist_set_dest ##### -->
+<para>
+
+</para>
+
+@persist: 
+@value: 
+
+
+<!-- ##### FUNCTION ephy_embed_persist_set_embed ##### -->
+<para>
+
+</para>
+
+@persist: 
+@value: 
+
+
+<!-- ##### FUNCTION ephy_embed_persist_set_fc_title ##### -->
+<para>
+
+</para>
+
+@persist: 
+@value: 
+
+
+<!-- ##### FUNCTION ephy_embed_persist_set_fc_parent ##### -->
+<para>
+
+</para>
+
+@persist: 
+@value: 
+
+
+<!-- ##### FUNCTION ephy_embed_persist_set_flags ##### -->
+<para>
+
+</para>
+
+@persist: 
+@value: 
+
+
+<!-- ##### FUNCTION ephy_embed_persist_set_max_size ##### -->
+<para>
+
+</para>
+
+@persist: 
+@Param2: 
+
+
+<!-- ##### FUNCTION ephy_embed_persist_set_persist_key ##### -->
+<para>
+
+</para>
+
+@persist: 
+@value: 
+
+
+<!-- ##### FUNCTION ephy_embed_persist_set_source ##### -->
+<para>
+
+</para>
+
+@persist: 
+@value: 
+
+
+<!-- ##### FUNCTION ephy_embed_persist_get_dest ##### -->
+<para>
+
+</para>
+
+@persist: 
+@Returns: 
+
+
+<!-- ##### FUNCTION ephy_embed_persist_get_embed ##### -->
+<para>
+
+</para>
+
+@persist: 
+@Returns: 
+
+
+<!-- ##### FUNCTION ephy_embed_persist_get_fc_title ##### -->
+<para>
+
+</para>
+
+@persist: 
+@Returns: 
+
+
+<!-- ##### FUNCTION ephy_embed_persist_get_fc_parent ##### -->
+<para>
+
+</para>
+
+@persist: 
+@Returns: 
+
+
+<!-- ##### FUNCTION ephy_embed_persist_get_flags ##### -->
+<para>
+
+</para>
+
+@persist: 
+@Returns: 
+
+
+<!-- ##### FUNCTION ephy_embed_persist_get_max_size ##### -->
+<para>
+
+</para>
+
+@persist: 
+@Returns: 
+
+
+<!-- ##### FUNCTION ephy_embed_persist_get_persist_key ##### -->
+<para>
+
+</para>
+
+@persist: 
+@Returns: 
+
+
+<!-- ##### FUNCTION ephy_embed_persist_get_source ##### -->
+<para>
+
+</para>
+
+@persist: 
+@Returns: 
+
+
+<!-- ##### FUNCTION ephy_embed_persist_save ##### -->
+<para>
+
+</para>
+
+@persist: 
+@Returns: 
+
+
+<!-- ##### FUNCTION ephy_embed_persist_cancel ##### -->
+<para>
+
+</para>
+
+@persist: 
+
+
+<!-- ##### FUNCTION ephy_embed_persist_to_string ##### -->
+<para>
+
+</para>
+
+@persist: 
+@Returns: 
+
+
+<!-- ##### SIGNAL EphyEmbedPersist::cancelled ##### -->
+<para>
+
+</para>
+
+@ephyembedpersist: the object which received the signal.
+
+<!-- ##### SIGNAL EphyEmbedPersist::completed ##### -->
+<para>
+
+</para>
+
+@ephyembedpersist: the object which received the signal.
+
+<!-- ##### ARG EphyEmbedPersist:dest ##### -->
+<para>
+
+</para>
+
+<!-- ##### ARG EphyEmbedPersist:embed ##### -->
+<para>
+
+</para>
+
+<!-- ##### ARG EphyEmbedPersist:filechooser-parent ##### -->
+<para>
+
+</para>
+
+<!-- ##### ARG EphyEmbedPersist:filechooser-title ##### -->
+<para>
+
+</para>
+
+<!-- ##### ARG EphyEmbedPersist:flags ##### -->
+<para>
+
+</para>
+
+<!-- ##### ARG EphyEmbedPersist:max-size ##### -->
+<para>
+
+</para>
+
+<!-- ##### ARG EphyEmbedPersist:persist-key ##### -->
+<para>
+
+</para>
+
+<!-- ##### ARG EphyEmbedPersist:source ##### -->
+<para>
+
+</para>
+
diff --git a/embed/ephy-embed-persist.c b/embed/ephy-embed-persist.c
index 5431af1d9..48eeb2a30 100644
--- a/embed/ephy-embed-persist.c
+++ b/embed/ephy-embed-persist.c
@@ -82,12 +82,19 @@ ephy_embed_persist_get_type (void)
 
 		type = g_type_register_static (G_TYPE_OBJECT,
 					       "EphyEmbedPersist",
-					       &our_info, 0);
+					       &our_info, G_TYPE_FLAG_ABSTRACT);
 	}
 
 	return type;
 }
 
+/**
+ * ephy_embed_persist_set_dest:
+ * @persist: an #EphyEmbedPersist
+ * @value: the path to which @persist should save data
+ *
+ * Sets the path to which @persist should save data.
+ **/
 void
 ephy_embed_persist_set_dest (EphyEmbedPersist *persist,
 			     const char *value)
@@ -97,6 +104,18 @@ ephy_embed_persist_set_dest (EphyEmbedPersist *persist,
 	persist->priv->dest = g_strdup (value);
 }
 
+/**
+ * ephy_embed_persist_set_embed:
+ * @persist: an #EphyEmbedPersist
+ * @value: a parent #EphyEmbed
+ *
+ * Sets the #EphyEmbed from which @persist will download data.
+ *
+ * An #EphyEmbed is absolutely required to download if @persist's
+ * #EmbedPersistFlags include %EMBED_PERSIST_COPY_PAGE. Regardless, an
+ * #EphyEmbed should be set for <emphasis>every</emphasis> #EphyEmbedPersist,
+ * since it determines request information such as the referring page.
+ **/
 void
 ephy_embed_persist_set_embed (EphyEmbedPersist *persist,
 			      EphyEmbed *value)
@@ -106,6 +125,15 @@ ephy_embed_persist_set_embed (EphyEmbedPersist *persist,
 	persist->priv->embed = value;
 }
 
+/**
+ * ephy_embed_persist_set_fc_title:
+ * @persist: an #EphyEmbedPersist
+ * @value: the title to be displayed by the filechooser
+ *
+ * Sets the title of the filechooser window. The filechooser will only be
+ * displayed if %EMBED_PERSIST_ASK_DESTINATION has been set with
+ * ephy_embed_persist_set_flags().
+ **/
 void
 ephy_embed_persist_set_fc_title (EphyEmbedPersist *persist,
 				 const char *value)
@@ -115,6 +143,15 @@ ephy_embed_persist_set_fc_title (EphyEmbedPersist *persist,
 	persist->priv->fc_title = g_strdup (value);
 }
 
+/**
+ * ephy_embed_persist_set_fc_parent:
+ * @persist: an #EphyEmbedPersist
+ * @value: the #EphyWindow which should be the filechooser's parent
+ *
+ * Sets the #EphyWindow which should be @persist's filechooser's parent. The
+ * filechooser will only be displayed if %EMBED_PERSIST_ASK_DESTINATION has been
+ * set with ephy_embed_persist_set_flags().
+ **/
 void
 ephy_embed_persist_set_fc_parent (EphyEmbedPersist *persist,
 				  GtkWindow *value)
@@ -124,6 +161,13 @@ ephy_embed_persist_set_fc_parent (EphyEmbedPersist *persist,
 	persist->priv->fc_parent = value;
 }
 
+/**
+ * ephy_embed_persist_set_flags:
+ * @persist: an #EphyEmbedPersist
+ * @value: the desired #EmbedPersistFlags
+ *
+ * Sets the flags to be used for @persist's download.
+ **/
 void
 ephy_embed_persist_set_flags (EphyEmbedPersist *persist,
 			      EmbedPersistFlags value)
@@ -133,6 +177,18 @@ ephy_embed_persist_set_flags (EphyEmbedPersist *persist,
 	persist->priv->flags = value;
 }
 
+/**
+ * ephy_embed_persist_set_max_size:
+ * @persist: an #EphyEmbedPersist
+ * @value: maximum size of requested download, in bytes
+ *
+ * Sets the maximum size of @persist's download.
+ *
+ * If the requested file is discovered to be larger than @value, the download
+ * will be aborted. Note that @persist will have to actually begin downloading
+ * before it can abort, since it doesn't know the filesize before the download
+ * starts.
+ **/
 void
 ephy_embed_persist_set_max_size (EphyEmbedPersist *persist,
 				 long value)
@@ -142,6 +198,14 @@ ephy_embed_persist_set_max_size (EphyEmbedPersist *persist,
 	persist->priv->max_size = value;
 }
 
+/**
+ * ephy_embed_persist_set_persist_key:
+ * @persist: an #EphyEmbedPersist
+ * @value: a GConf key
+ *
+ * Sets the GConf key from which @persist will determine the default download
+ * directory.
+ **/
 void
 ephy_embed_persist_set_persist_key (EphyEmbedPersist *persist,
 				    const char *value)
@@ -151,6 +215,14 @@ ephy_embed_persist_set_persist_key (EphyEmbedPersist *persist,
 	persist->priv->persist_key = g_strdup (value);
 }
 
+/**
+ * ephy_embed_persist_set_source:
+ * @persist: an #EphyEmbedPersist
+ * @value: the URL from which @persist should download
+ *
+ * Sets the URL from which @persist should download. This should be used in
+ * conjunction with ephy_embed_persist_set_embed().
+ **/
 void
 ephy_embed_persist_set_source (EphyEmbedPersist *persist,
 			       const char *value)
@@ -160,6 +232,14 @@ ephy_embed_persist_set_source (EphyEmbedPersist *persist,
 	persist->priv->source = g_strdup (value);
 }
 
+/**
+ * ephy_embed_persist_get_dest:
+ * @persist: an #EphyEmbedPersist
+ *
+ * Returns the destination filename to which @persist will save its download.
+ *
+ * Return value: @persist's destination filename
+ **/
 const char *
 ephy_embed_persist_get_dest (EphyEmbedPersist *persist)
 {
@@ -168,6 +248,14 @@ ephy_embed_persist_get_dest (EphyEmbedPersist *persist)
 	return persist->priv->dest;
 }
 
+/**
+ * ephy_embed_persist_get_embed:
+ * @persist: an #EphyEmbedPersist
+ *
+ * Returns the #EphyEmbed from which @persist will download.
+ *
+ * Return value: the #EphyEmbed from which @persist will download
+ **/
 EphyEmbed *
 ephy_embed_persist_get_embed (EphyEmbedPersist *persist)
 {
@@ -176,6 +264,14 @@ ephy_embed_persist_get_embed (EphyEmbedPersist *persist)
 	return persist->priv->embed;
 }
 
+/**
+ * ephy_embed_persist_get_fc_title:
+ * @persist: an #EphyEmbedPersist
+ *
+ * Returns the title to be displayed in @persist's filechooser.
+ *
+ * Return value: the title to be displayed in @persist's filechooser
+ **/
 const char *
 ephy_embed_persist_get_fc_title (EphyEmbedPersist *persist)
 {
@@ -184,6 +280,15 @@ ephy_embed_persist_get_fc_title (EphyEmbedPersist *persist)
 	return persist->priv->fc_title;
 }
 
+/**
+ * ephy_embed_persist_get_fc_parent:
+ * @persist: an #EphyEmbedPersist
+ *
+ * Returns the #EphyWindow which should serve as a parent for @persist's
+ * filechooser.
+ *
+ * Return value: the #EphyWindow parent for @persist's filechooser
+ **/
 GtkWindow *
 ephy_embed_persist_get_fc_parent (EphyEmbedPersist *persist)
 {
@@ -192,6 +297,14 @@ ephy_embed_persist_get_fc_parent (EphyEmbedPersist *persist)
 	return persist->priv->fc_parent;
 }
 
+/**
+ * ephy_embed_persist_get_flags:
+ * @persist: an #EphyEmbedPersist
+ *
+ * Returns @persist's #EmbedPersistFlags.
+ *
+ * Return value: @persist's #EmbedPersistFlags
+ **/
 EmbedPersistFlags
 ephy_embed_persist_get_flags (EphyEmbedPersist *persist)
 {
@@ -200,7 +313,15 @@ ephy_embed_persist_get_flags (EphyEmbedPersist *persist)
 	return persist->priv->flags;
 }
 
-int
+/**
+ * ephy_embed_persist_get_max_size:
+ * @persist: an #EphyEmbedPersist
+ *
+ * Returns the maximum size of @persist's requested download, in bytes.
+ *
+ * Return value: the maximum size of @persist's requested download, in bytes
+ **/
+long
 ephy_embed_persist_get_max_size (EphyEmbedPersist *persist)
 {
 	g_return_val_if_fail (EPHY_IS_EMBED_PERSIST (persist), 0);
@@ -208,6 +329,14 @@ ephy_embed_persist_get_max_size (EphyEmbedPersist *persist)
 	return persist->priv->max_size;
 }
 
+/**
+ * ephy_embed_persist_get_persist_key:
+ * @persist: an #EphyEmbedPersist
+ *
+ * Returns the GConf key which determines Epiphany's default download directory.
+ *
+ * Return value: the GConf key to the default download directory
+ **/
 const char *
 ephy_embed_persist_get_persist_key (EphyEmbedPersist *persist)
 {
@@ -216,6 +345,14 @@ ephy_embed_persist_get_persist_key (EphyEmbedPersist *persist)
 	return persist->priv->persist_key;
 }
 
+/**
+ * ephy_embed_persist_get_source:
+ * @persist: an #EphyEmbedPersist
+ *
+ * Returns the source URL of the file to download.
+ *
+ * Return value: a source URL
+ **/
 const char *
 ephy_embed_persist_get_source (EphyEmbedPersist *persist)
 {
@@ -341,6 +478,12 @@ ephy_embed_persist_class_init (EphyEmbedPersistClass *klass)
 	object_class->get_property = ephy_embed_persist_get_property;
 
 	/* init signals */
+/**
+ * EphyEmbedPersist::completed:
+ *
+ * The ::completed signal is emitted when @persist has finished downloading. The
+ * download must have started with ephy_embed_persist_save().
+ **/
 	g_signal_new ("completed",
 		      G_OBJECT_CLASS_TYPE (object_class),
 		      G_SIGNAL_RUN_LAST,
@@ -349,6 +492,12 @@ ephy_embed_persist_class_init (EphyEmbedPersistClass *klass)
 		      g_cclosure_marshal_VOID__VOID,
 		      G_TYPE_NONE,
 		      0);
+/**
+ * EphyEmbedPersist::cancelled:
+ *
+ * The ::cancelled signal is emitted when @persist's download has been
+ * cancelled with ephy_embed_persist_cancel().
+ **/
 	g_signal_new ("cancelled",
 		      G_OBJECT_CLASS_TYPE (object_class),
 		      G_SIGNAL_RUN_LAST,
@@ -430,6 +579,13 @@ ephy_embed_persist_class_init (EphyEmbedPersistClass *klass)
 	g_type_class_add_private (object_class, sizeof(EphyEmbedPersistPrivate));
 }
 
+/**
+ * ephy_embed_persist_cancel:
+ * @persist: an #EphyEmbedPersist
+ *
+ * Cancels @persist's download. This will not delete the partially downloaded
+ * file.
+ **/
 void
 ephy_embed_persist_cancel (EphyEmbedPersist *persist)
 {
@@ -437,12 +593,45 @@ ephy_embed_persist_cancel (EphyEmbedPersist *persist)
 	klass->cancel (persist);
 }
 
+/**
+ * ephy_embed_persist_save:
+ * @persist: an #EphyEmbedPersist
+ *
+ * Begins saving the file specified in @persist.
+ *
+ * If @persist's #EmbedPersistFlags include %EMBED_PERSIST_ASK_DESTINATION, a
+ * filechooser dialog will be shown first.
+ *
+ * The file will continue to download in the background until either the
+ * ::completed or the ::cancelled signals are emitted by @persist.
+ *
+ * Return value: %TRUE if the download began successfully
+ **/
 gboolean
 ephy_embed_persist_save (EphyEmbedPersist *persist)
 {
 	EphyEmbedPersistClass *klass = EPHY_EMBED_PERSIST_GET_CLASS (persist);
 	return klass->save (persist);
 }
+
+/**
+ * ephy_embed_persist_to_string:
+ * @persist: an #EphyEmbedPersist
+ *
+ * Returns the download specified by @persist as a string instead of downloading
+ * it to a file.
+ *
+ * The download is synchronous. An #EphyEmbed must be specified with
+ * ephy_embed_persist_set_embed(). The function implicitly assumes that
+ * @persist's #EmbedPersistFlags include %EMBED_PERSIST_COPY_PAGE. If @persist's
+ * #EphyEmbed has not finished downloading, this function will only return the
+ * portion of data which has already been downloaded.
+ *
+ * The document will be modified: it will only include absolute links and it
+ * will be encoded as UTF-8.
+ *
+ * Return value: The contents of @persist's #EphyEmbed's web page
+ **/
 char *
 ephy_embed_persist_to_string (EphyEmbedPersist *persist)
 {
diff --git a/embed/ephy-embed-persist.h b/embed/ephy-embed-persist.h
index dbd0272ae..2d785bfaa 100644
--- a/embed/ephy-embed-persist.h
+++ b/embed/ephy-embed-persist.h
@@ -38,8 +38,8 @@ G_BEGIN_DECLS
 #define EPHY_IS_EMBED_PERSIST_CLASS(k)	(G_TYPE_CHECK_CLASS_TYPE ((k), EPHY_TYPE_EMBED_PERSIST))
 #define EPHY_EMBED_PERSIST_GET_CLASS(o)	(G_TYPE_INSTANCE_GET_CLASS ((o), EPHY_TYPE_EMBED_PERSIST, EphyEmbedPersistClass))
 
-typedef struct EphyEmbedPersistClass EphyEmbedPersistClass;
-typedef struct EphyEmbedPersist EphyEmbedPersist;
+typedef struct _EphyEmbedPersistClass EphyEmbedPersistClass;
+typedef struct _EphyEmbedPersist EphyEmbedPersist;
 typedef struct EphyEmbedPersistPrivate EphyEmbedPersistPrivate;
 
 typedef enum
@@ -50,7 +50,7 @@ typedef enum
 	EMBED_PERSIST_ASK_DESTINATION	= 1 << 3
 } EmbedPersistFlags;
 
-struct EphyEmbedPersist
+struct _EphyEmbedPersist
 {
 	GObject parent;
 
@@ -58,7 +58,7 @@ struct EphyEmbedPersist
 	EphyEmbedPersistPrivate *priv;
 };
 
-struct EphyEmbedPersistClass
+struct _EphyEmbedPersistClass
 {
 	GObjectClass parent_class;
 
@@ -113,7 +113,7 @@ GtkWindow		*ephy_embed_persist_get_fc_parent	(EphyEmbedPersist *persist);
 
 EmbedPersistFlags	 ephy_embed_persist_get_flags		(EphyEmbedPersist *persist);
 
-int			 ephy_embed_persist_get_max_size	(EphyEmbedPersist *persist);
+long			 ephy_embed_persist_get_max_size	(EphyEmbedPersist *persist);
 
 const char 		*ephy_embed_persist_get_persist_key	(EphyEmbedPersist *persist);