Documented EphyNodeDb

11 files changed, 169 insertions, 16 deletions

diff --git a/ChangeLog b/ChangeLog
index 344df0d11..086cde86a 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,33 @@
+2004-04-04  Adam Hooper  <adamh@cvs.gnome.org>
+
+	* HACKING:
+
+	Suggest /* to open comments instead of /** (rationale: gtk-doc)
+
+	* src/ephy-tab.c: (ephy_tab_set_title):
+
+	Change /** to /*
+
+	* doc/reference/Makefile.am:
+	* doc/reference/epiphany-docs.sgml:
+	* doc/reference/epiphany-sections.txt:
+	* lib/ephy-node-db.c: (node_from_id_real),
+	(ephy_node_db_get_node_from_id), (_ephy_node_db_new_id),
+	(_ephy_node_db_add_id), (_ephy_node_db_remove_id):
+	* lib/ephy-node-db.h:
+
+	Documented EphyNodeDb. Changed the ids to guints to conform with
+	GPtrArray.
+
+	* doc/reference/tmpl/ephy-tab.sgml:
+
+	Say how to get an EphyWindow from an EphyEmbed
+
+	* doc/reference/tmpl/ephy-embed-persist.sgml:
+	* doc/reference/tmpl/ephy-embed.sgml:
+
+	Automatically changed when I rebuilt docs
+
 2004-04-03  Crispin Flowerday  <gnome@flowerday.cx>
 
 	* lib/egg/egg-editable-toolbar.c: (set_fixed_style),
diff --git a/HACKING b/HACKING
index 31bef1cb9..60e3807e9 100644
--- a/HACKING
+++ b/HACKING
@@ -8,7 +8,7 @@ need to stick to in order to get your patch accepted:
 
   Comment blocks are written like this:
   
-/**
+/*
  * bla_bla_cb: This is an example comment block
  */
 
diff --git a/doc/reference/Makefile.am b/doc/reference/Makefile.am
index a86f6ba82..2e5373c54 100644
--- a/doc/reference/Makefile.am
+++ b/doc/reference/Makefile.am
@@ -44,7 +44,6 @@ IGNORE_HFILES = \
 	ephy-marshal.h \
 	ephy-module-loader.h \
 	ephy-node-common.h \
-	ephy-node-db.h \
 	ephy-node-filter.h \
 	ephy-node.h \
 	ephy-prefs.h \
diff --git a/doc/reference/epiphany-docs.sgml b/doc/reference/epiphany-docs.sgml
index 71605bb0b..ad600c820 100644
--- a/doc/reference/epiphany-docs.sgml
+++ b/doc/reference/epiphany-docs.sgml
@@ -16,6 +16,7 @@
     <xi:include href="xml/ephy-embed-single.xml"/>
     <xi:include href="xml/ephy-embed-persist.xml"/>
     <xi:include href="xml/ephy-embed-factory.xml"/>
+    <xi:include href="xml/ephy-node-db.xml"/>
   </chapter>
   <chapter>
     <title>Incomplete</title>
diff --git a/doc/reference/epiphany-sections.txt b/doc/reference/epiphany-sections.txt
index 390997e5b..a08ed80a8 100644
--- a/doc/reference/epiphany-sections.txt
+++ b/doc/reference/epiphany-sections.txt
@@ -206,6 +206,28 @@ EPHY_IS_COMMAND_MANAGER_IFACE
 ephy_embed_factory_new_object
 </SECTION>
 
+<SECTION>
+<FILE>ephy-node-db</FILE>
+<TITLE>EphyNodeDb</TITLE>
+EphyNodeDb
+ephy_node_db_get_by_name
+ephy_node_db_new
+ephy_node_db_load_from_file
+ephy_node_db_write_to_xml_safe
+ephy_node_db_get_name
+ephy_node_db_is_immutable
+ephy_node_db_set_immutable
+ephy_node_db_get_node_from_id
+<SUBSECTION Standard>
+EPHY_NODE_DB
+EPHY_IS_NODE_DB
+EPHY_TYPE_NODE_DB
+ephy_node_db_get_type
+EPHY_NODE_DB_CLASS
+EPHY_IS_NODE_DB_CLASS
+EPHY_NODE_DB_GET_CLASS
+</SECTION>
+
 
 
 
diff --git a/doc/reference/tmpl/ephy-embed-persist.sgml b/doc/reference/tmpl/ephy-embed-persist.sgml
index be75437c8..e280a76da 100644
--- a/doc/reference/tmpl/ephy-embed-persist.sgml
+++ b/doc/reference/tmpl/ephy-embed-persist.sgml
@@ -134,6 +134,8 @@ Determines how the #EphyEmbedPersist should act.
 
 @persist: 
 @Param2: 
+<!-- # Unused Parameters # -->
+@value: 
 
 
 <!-- ##### FUNCTION ephy_embed_persist_set_persist_key ##### -->
diff --git a/doc/reference/tmpl/ephy-embed.sgml b/doc/reference/tmpl/ephy-embed.sgml
index c57e5cf98..1fd4d6784 100644
--- a/doc/reference/tmpl/ephy-embed.sgml
+++ b/doc/reference/tmpl/ephy-embed.sgml
@@ -120,6 +120,7 @@ windows opened with JavaScript often use a nonstandard chrome.
 			    to display its toolbars.
 @EPHY_EMBED_CHROME_STATUSBAR: %TRUE for the #EphyEmbed's containing #EphyWindow
 			      to display its statusbar.
+@EPHY_EMBED_CHROME_BOOKMARKSBAR: 
 
 <!-- ##### ENUM EmbedReloadFlags ##### -->
 <para>
diff --git a/doc/reference/tmpl/ephy-tab.sgml b/doc/reference/tmpl/ephy-tab.sgml
index ae5eba7b0..541aeef5f 100644
--- a/doc/reference/tmpl/ephy-tab.sgml
+++ b/doc/reference/tmpl/ephy-tab.sgml
@@ -9,6 +9,9 @@ Represents an Epiphany tab
 Each #EphyWindow contains a #GtkNotebook which holds one or more #EphyTab:s.
 An #EphyTab is basically a container for an #EphyEmbed.
 </para>
+<para>
+To retrieve an #EphyTab's parent #EphyWindow, use gtk_widget_get_toplevel().
+</para>
 
 <!-- ##### SECTION See_Also ##### -->
 <para>
diff --git a/lib/ephy-node-db.c b/lib/ephy-node-db.c
index e99743914..0eaf92755 100644
--- a/lib/ephy-node-db.c
+++ b/lib/ephy-node-db.c
@@ -55,7 +55,7 @@ struct EphyNodeDbPrivate
 	char *name;
 	gboolean immutable;
 
-	long id_factory;
+	guint id_factory;
 
 	GPtrArray *id_to_node;
 };
@@ -207,6 +207,14 @@ ephy_node_db_finalize (GObject *object)
 	G_OBJECT_CLASS (parent_class)->finalize (object);
 }
 
+/**
+ * ephy_node_db_get_by_name:
+ * @name: the name of the desired #EphyNodeDb
+ *
+ * Returns the #EphyNodeDb named @name, or %NULL if no such database exists.
+ *
+ * Return value: an #EphyNodeDb
+ **/
 EphyNodeDb *
 ephy_node_db_get_by_name (const char *name)
 {
@@ -217,6 +225,14 @@ ephy_node_db_get_by_name (const char *name)
 	return ret;
 }
 
+/**
+ * ephy_node_db_new:
+ * @name: the name of the new #EphyNodeDb
+ *
+ * Creates and returns a new #EphyNodeDb, named @name.
+ *
+ * Return value: the new #EphyNodeDb
+ **/
 EphyNodeDb *
 ephy_node_db_new (const char *name)
 {
@@ -232,7 +248,7 @@ ephy_node_db_new (const char *name)
 }
 
 static inline EphyNode *
-node_from_id_real (EphyNodeDb *db, long id)
+node_from_id_real (EphyNodeDb *db, guint id)
 {
 	EphyNode *ret = NULL;
 
@@ -242,18 +258,38 @@ node_from_id_real (EphyNodeDb *db, long id)
 	return ret;
 }
 
+/**
+ * ephy_node_db_get_name:
+ * @db: an #EphyNodeDb
+ *
+ * Return value: the name of @db
+ **/
 const char *
 ephy_node_db_get_name (EphyNodeDb *db)
 {
 	return db->priv->name;
 }
 
+/**
+ * ephy_node_db_is_immutable:
+ * @db: an #EphyNodeDb
+ *
+ * Return value: %TRUE if @db is immutable
+ **/
 gboolean
 ephy_node_db_is_immutable (EphyNodeDb *db)
 {
 	return db->priv->immutable;
 }
 
+/**
+ * ephy_node_db_set_immutable:
+ * @db: an #EphyNodeDb
+ * @immutable: %TRUE to make @db immutable
+ *
+ * If @immutable is %TRUE, sets @db immutable (read-only). Otherwise, sets @db
+ * to be read-write.
+ **/
 void
 ephy_node_db_set_immutable (EphyNodeDb *db, gboolean immutable)
 {
@@ -262,8 +298,17 @@ ephy_node_db_set_immutable (EphyNodeDb *db, gboolean immutable)
 	g_object_notify (G_OBJECT (db), "immutable");
 }
 
+/**
+ * ephy_node_db_get_node_from_id:
+ * @db: an #EphyNodeDb
+ * @id: an id specifying an #EphyNode in @db
+ *
+ * Returns the #EphyNode with id @id from @db, or %NULL if no such id exists.
+ *
+ * Return value: an #EphyNode
+ **/
 EphyNode *
-ephy_node_db_get_node_from_id (EphyNodeDb *db, long id)
+ephy_node_db_get_node_from_id (EphyNodeDb *db, guint id)
 {
 	EphyNode *ret = NULL;
 
@@ -272,10 +317,10 @@ ephy_node_db_get_node_from_id (EphyNodeDb *db, long id)
 	return ret;
 }
 
-long
+guint
 _ephy_node_db_new_id (EphyNodeDb *db)
 {
-	long ret;
+	guint ret;
 
 	while (node_from_id_real (db, db->priv->id_factory) != NULL)
 	{
@@ -289,7 +334,7 @@ _ephy_node_db_new_id (EphyNodeDb *db)
 
 void
 _ephy_node_db_add_id (EphyNodeDb *db,
-		      long id,
+		      guint id,
 		      EphyNode *node)
 {
 	/* resize array if needed */
@@ -301,7 +346,7 @@ _ephy_node_db_add_id (EphyNodeDb *db,
 
 void
 _ephy_node_db_remove_id (EphyNodeDb *db,
-			 long id)
+			 guint id)
 {
 	g_ptr_array_index (db->priv->id_to_node, id) = NULL;
 
@@ -309,6 +354,23 @@ _ephy_node_db_remove_id (EphyNodeDb *db,
 	db->priv->id_factory = RESERVED_IDS;
 }
 
+/**
+ * ephy_node_db_load_from_file:
+ * @db: a new #EphyNodeDb
+ * @xml_file: the filename from which @db will be populated
+ * @xml_root: the root element in @xml_file
+ * @xml_version: the required version attribute in the @xml_root
+ *
+ * Populates @db with data from @xml_file. The node database will be populated
+ * with everything inside of the @xml_root tag from @xml_file. If @xml_version
+ * is different from the version attribute of the @xml_root element, this
+ * function will fail.
+ *
+ * The data will most probably have been stored using
+ * ephy_node_db_write_to_xml_safe().
+ *
+ * Return value: %TRUE if successful
+ **/
 gboolean
 ephy_node_db_load_from_file (EphyNodeDb *db,
 			     const char *xml_file,
@@ -489,6 +551,39 @@ out:
 	return ret >= 0 ? 0 : -1;
 }
 
+/**
+ * ephy_node_db_write_to_xml_safe:
+ * @db: an #EphyNodeDb
+ * @filename: the XML file in which @db's data will be stored
+ * @root: the desired root element in @filename
+ * @version: the version attribute to the @root element
+ * @comment: a comment to place directly inside the @root element of @filename
+ * @node: The first node of data to write
+ * @Varargs: number of exceptions, list of their #EphyNodes, and more such
+ * 	     sequences, followed by %NULL
+ *
+ * Writes @db's data to an XML file for storage. The data can be retrieved in
+ * the future using ephy_node_db_load_from_file().
+ *
+ * The function arguments are straightforward until @node, at which point some
+ * explanation is necessary.
+ *
+ * The variable argument list starts at @node, which is an #EphyNode containing
+ * data to write to @filename. The next argument is an integer specifying the
+ * number of <quote>exception</quote> nodes. After this integer, that number of
+ * #EphyNode arguments should be given. Each of these <quote>exception</quote>
+ * nodes determines which data out of @node will <emphasis>not</emphasis> be
+ * written to @filename.
+ *
+ * To insert all of an #EphyNode's contents without exception, simply give the
+ * integer %0 after @node.
+ *
+ * The remainder of this function's arguments will be groups of such #EphyNode -
+ * integer - (list of #EphyNode<!-- -->s). Finally, the last argument must be
+ * %NULL.
+ *
+ * Return value: %0 on success or a negative number on failure
+ **/
 int
 ephy_node_db_write_to_xml_safe (EphyNodeDb *db,
 				const xmlChar *filename,
diff --git a/lib/ephy-node-db.h b/lib/ephy-node-db.h
index f6138a427..e181356e8 100644
--- a/lib/ephy-node-db.h
+++ b/lib/ephy-node-db.h
@@ -34,10 +34,10 @@ G_BEGIN_DECLS
 #define EPHY_IS_NODE_DB_CLASS(k)  (G_TYPE_CHECK_CLASS_TYPE ((k), EPHY_TYPE_NODE_DB))
 #define EPHY_NODE_DB_GET_CLASS(o) (G_TYPE_INSTANCE_GET_CLASS ((o), EPHY_TYPE_NODE_DB, EphyNodeDbClass))
 
-typedef struct EphyNodeDb EphyNodeDb;
+typedef struct _EphyNodeDb EphyNodeDb;
 typedef struct EphyNodeDbPrivate EphyNodeDbPrivate;
 
-struct EphyNodeDb
+struct _EphyNodeDb
 {
 	GObject parent;
 
@@ -79,16 +79,16 @@ void	      ephy_node_db_set_immutable	(EphyNodeDb *db,
 						 gboolean immutable);
 
 EphyNode     *ephy_node_db_get_node_from_id	(EphyNodeDb *db,
-						 long id);
+						 guint id);
 
-long	      _ephy_node_db_new_id		(EphyNodeDb *db);
+guint	      _ephy_node_db_new_id		(EphyNodeDb *db);
 
 void	      _ephy_node_db_add_id		(EphyNodeDb *db,
-						 long id,
+						 guint id,
 						 EphyNode *node);
 
 void	      _ephy_node_db_remove_id		(EphyNodeDb *db,
-						 long id);
+						 guint id);
 
 G_END_DECLS
 
diff --git a/src/ephy-tab.c b/src/ephy-tab.c
index db364b9f1..179d86b3d 100644
--- a/src/ephy-tab.c
+++ b/src/ephy-tab.c
@@ -1459,7 +1459,7 @@ ephy_tab_set_title (EphyTab *tab, EphyEmbed *embed, const char *new_title)
 	title_short = ephy_string_shorten (title, MAX_LABEL_LENGTH);
 	title_tmp = ephy_string_double_underscores (title_short);
 
-	/**
+	/*
 	 * FIXME: instead of shortening the title here, use an egg action
 	 * which creates menu items with ellipsizing labels
 	 */