[epiphany/origin/master: 13/19] docs: ephy-tree-model-node

[Diego Escalante Urrelo <diegoe src gnome org>]

commit 57d1e4a28256b3204b9cbcadd6f52832e55a477c
Author: Diego Escalante Urrelo <diegoe gnome org>
Date:   Tue Dec 1 21:24:38 2009 -0500

    docs: ephy-tree-model-node
    
    Bug #503852

 doc/reference/epiphany-docs.sgml    |    1 +
 doc/reference/epiphany-sections.txt |   11 ++++++
 doc/reference/epiphany.types        |    1 +
 lib/widgets/ephy-tree-model-node.c  |   59 +++++++++++++++++++++++++++++++++++
 lib/widgets/ephy-tree-model-node.h  |   10 +++--
 5 files changed, 78 insertions(+), 4 deletions(-)
---
diff --git a/doc/reference/epiphany-docs.sgml b/doc/reference/epiphany-docs.sgml
index ccddd27..aba30d8 100644
--- a/doc/reference/epiphany-docs.sgml
+++ b/doc/reference/epiphany-docs.sgml
@@ -15,6 +15,7 @@
     <xi:include href="xml/ephy-node-view.xml"/>
     <xi:include href="xml/ephy-search-entry.xml"/>
     <xi:include href="xml/ephy-spinner.xml"/>
+    <xi:include href="xml/ephy-tree-model-node.xml"/>
     <xi:include href="xml/ephy-tree-model-sort.xml"/>
     <xi:include href="xml/ephy-zoom-action.xml"/>
     <xi:include href="xml/ephy-zoom-control.xml"/>
diff --git a/doc/reference/epiphany-sections.txt b/doc/reference/epiphany-sections.txt
index 9faeac8..7fee4ce 100644
--- a/doc/reference/epiphany-sections.txt
+++ b/doc/reference/epiphany-sections.txt
@@ -60,6 +60,17 @@ ephy_spinner_set_size
 </SECTION>
 
 <SECTION>
+<FILE>ephy-tree-model-node</FILE>
+<TITLE>EphyTreeModelNode</TITLE>
+EphyTreeModelNode
+ephy_tree_model_node_new
+ephy_tree_model_node_add_prop_column
+ephy_tree_model_node_add_func_column
+ephy_tree_model_node_node_from_iter
+ephy_tree_model_node_iter_from_node
+</SECTION>
+
+<SECTION>
 <FILE>ephy-tree-model-sort</FILE>
 <TITLE>EphyTreeModelSort</TITLE>
 EphyTreeModelSort
diff --git a/doc/reference/epiphany.types b/doc/reference/epiphany.types
index 160214b..199f267 100644
--- a/doc/reference/epiphany.types
+++ b/doc/reference/epiphany.types
@@ -10,6 +10,7 @@ ephy_node_view_get_type
 ephy_location_entry_get_type
 ephy_search_entry_get_type
 ephy_spinner_get_type
+ephy_tree_model_node_get_type
 ephy_tree_model_sort_get_type
 ephy_zoom_action_get_type
 ephy_zoom_control_get_type
diff --git a/lib/widgets/ephy-tree-model-node.c b/lib/widgets/ephy-tree-model-node.c
index 916fae5..bbd3a2b 100644
--- a/lib/widgets/ephy-tree-model-node.c
+++ b/lib/widgets/ephy-tree-model-node.c
@@ -28,6 +28,14 @@
 #include "ephy-node.h"
 #include "ephy-debug.h"
 
+/**
+ * SECTION:ephy-tree-model-node
+ * @short_description: a #GtkTreeModel of #EphyNode elements
+ *
+ * #EphyTreeModelNode implements a #GtkTreeModel that holds #EphyNode elements.
+ * It can be used with #EphyNodeView and #EphyTreeModelFilter.
+ */
+
 static void ephy_tree_model_node_class_init (EphyTreeModelNodeClass *klass);
 static void ephy_tree_model_node_init (EphyTreeModelNode *model);
 static void ephy_tree_model_node_finalize (GObject *object);
@@ -270,6 +278,11 @@ ephy_tree_model_node_class_init (EphyTreeModelNodeClass *klass)
 	object_class->set_property = ephy_tree_model_node_set_property;
 	object_class->get_property = ephy_tree_model_node_get_property;
 
+	/**
+	* EphyTreeModelNode:root:
+	*
+	* The root #EphyNode of the model.
+	*/
 	g_object_class_install_property (object_class,
 					 PROP_ROOT,
 					 g_param_spec_pointer ("root",
@@ -300,6 +313,14 @@ ephy_tree_model_node_finalize (GObject *object)
 	G_OBJECT_CLASS (parent_class)->finalize (object);
 }
 
+/**
+ * ephy_tree_model_node_new:
+ * @root: root #EphyNode of the model
+ *
+ * Create a new #EphyTreeModelNode object and set @root as its root node.
+ *
+ * Returns: a new #EphyTreeModelNode
+ **/
 EphyTreeModelNode *
 ephy_tree_model_node_new (EphyNode *root)
 {
@@ -314,6 +335,16 @@ ephy_tree_model_node_new (EphyNode *root)
 	return model;
 }
 
+/**
+ * ephy_tree_model_node_add_prop_column:
+ * @model: an #EphyTreeModelNode
+ * @value_type: type held by the new column
+ * @prop_id: column in @model to get the value for this column
+ *
+ * Add a new column to @model obtaining its value from @prop_id in @model.
+ *
+ * Returns: the id of the new column
+ **/
 int
 ephy_tree_model_node_add_prop_column (EphyTreeModelNode *model,
 				      GType value_type,
@@ -335,6 +366,17 @@ ephy_tree_model_node_add_prop_column (EphyTreeModelNode *model,
 	return col_id;
 }
 
+/**
+ * ephy_tree_model_node_add_func_column:
+ * @model: an #EphyTreeModelNode
+ * @value_type: type held by the new column
+ * @func: data function to be used to provide the value of the new column
+ * @user_data: optional user data for @func
+ *
+ * Adds a new column to @model with its value determined by @func.
+ *
+ * Returns: the id of the new column
+ **/
 int
 ephy_tree_model_node_add_func_column (EphyTreeModelNode *model,
 				      GType value_type,
@@ -581,6 +623,15 @@ ephy_tree_model_node_iter_parent (GtkTreeModel *tree_model,
 	return FALSE;
 }
 
+/**
+ * ephy_tree_model_node_node_from_iter:
+ * @model: an #EphyTreeModelNode
+ * @iter: iter from where to get the node
+ *
+ * Gets the #EphyNode corresponding to @iter from @model.
+ *
+ * Returns: the #EphyNode corresponding to @iter
+ **/
 EphyNode *
 ephy_tree_model_node_node_from_iter (EphyTreeModelNode *model,
 				     GtkTreeIter *iter)
@@ -588,6 +639,14 @@ ephy_tree_model_node_node_from_iter (EphyTreeModelNode *model,
 	return iter->user_data;
 }
 
+/**
+ * ephy_tree_model_node_iter_from_node:
+ * @model: an #EphyTreeModelNode
+ * @node: the #EphyNode from which we want the iter to be obtained
+ * @iter: location to return the #GtkTreeIter
+ *
+ * Gets the corresponding #GtkTreeIter for @node from @model.
+ **/
 void
 ephy_tree_model_node_iter_from_node (EphyTreeModelNode *model,
 				     EphyNode *node,
diff --git a/lib/widgets/ephy-tree-model-node.h b/lib/widgets/ephy-tree-model-node.h
index 8a277be..9a1053a 100644
--- a/lib/widgets/ephy-tree-model-node.h
+++ b/lib/widgets/ephy-tree-model-node.h
@@ -35,20 +35,22 @@ G_BEGIN_DECLS
 
 typedef void (*EphyTreeModelNodeValueFunc) (EphyNode *node, GValue *value, gpointer user_data);
 
+typedef struct _EphyTreeModelNode EphyTreeModelNode;
+typedef struct _EphyTreeModelNodeClass EphyTreeModelNodeClass;
 typedef struct _EphyTreeModelNodePrivate EphyTreeModelNodePrivate;
 
-typedef struct
+struct _EphyTreeModelNode
 {
 	GObject parent;
 
 	/*< private >*/
 	EphyTreeModelNodePrivate *priv;
-} EphyTreeModelNode;
+};
 
-typedef struct
+struct _EphyTreeModelNodeClass
 {
 	GObjectClass parent;
-} EphyTreeModelNodeClass;
+};
 
 GType              ephy_tree_model_node_get_type         (void);