[gnome-builder/gnome-builder-3-18] tree: make GbTree introspectiable and public API

[Christian Hergert <chergert src gnome org>]

commit ef3ea7f2bbdb458b34313c12f6c1776aa05dafbb
Author: Christian Hergert <christian hergert me>
Date:   Sat Sep 26 21:17:46 2015 -0700

    tree: make GbTree introspectiable and public API

 src/Makefile.am         |   16 ++++++++--------
 src/tree/gb-tree-node.c |   27 +++++++++++++++++++++------
 src/tree/gb-tree-node.h |    2 +-
 src/tree/gb-tree.c      |   29 ++++++++++++++++++++---------
 4 files changed, 50 insertions(+), 24 deletions(-)
---
diff --git a/src/Makefile.am b/src/Makefile.am
index fc9682e..a8adf2e 100644
--- a/src/Makefile.am
+++ b/src/Makefile.am
@@ -21,6 +21,14 @@ libgnome_builder_public_sources = \
        editor/gb-editor-view-addin.h \
        util/gb-menu-extension.c \
        util/gb-menu-extension.h \
+       tree/gb-tree-builder.c \
+       tree/gb-tree-builder.h \
+       tree/gb-tree.c \
+       tree/gb-tree.h \
+       tree/gb-tree-node.c \
+       tree/gb-tree-node.h \
+       tree/gb-tree-private.h \
+       tree/gb-tree-types.h \
        views/gb-view.c \
        views/gb-view.h \
        views/gb-view-stack.c \
@@ -130,14 +138,6 @@ libgnome_builder_la_SOURCES = \
        search/gb-search-display.h \
        support/gb-support.c \
        support/gb-support.h \
-       tree/gb-tree-builder.c \
-       tree/gb-tree-builder.h \
-       tree/gb-tree.c \
-       tree/gb-tree.h \
-       tree/gb-tree-node.c \
-       tree/gb-tree-node.h \
-       tree/gb-tree-private.h \
-       tree/gb-tree-types.h \
        util/gb-cairo.c \
        util/gb-cairo.h \
        util/gb-dnd.c \
diff --git a/src/tree/gb-tree-node.c b/src/tree/gb-tree-node.c
index 170085a..cba406f 100644
--- a/src/tree/gb-tree-node.c
+++ b/src/tree/gb-tree-node.c
@@ -123,6 +123,15 @@ _gb_tree_node_set_tree (GbTreeNode *node,
     }
 }
 
+/**
+ * gb_tree_node_insert_sorted:
+ * @node: A #GbTreeNode.
+ * @child: A #GbTreeNode.
+ * @compare_func: (scope call): A compare func to compare nodes.
+ * @user_data: (closure compare_func): user data for @compare_func.
+ *
+ * Inserts a @child as a child of @node, sorting it among the other children.
+ */
 void
 gb_tree_node_insert_sorted (GbTreeNode            *node,
                             GbTreeNode            *child,
@@ -138,7 +147,8 @@ gb_tree_node_insert_sorted (GbTreeNode            *node,
 
 /**
  * gb_tree_node_append:
- * @node: (in): A #GbTreeNode.
+ * @node: A #GbTreeNode.
+ * @child: A #GbTreeNode.
  *
  * Appends @child to the list of children owned by @node.
  */
@@ -153,7 +163,8 @@ gb_tree_node_append (GbTreeNode *node,
 
 /**
  * gb_tree_node_prepend:
- * @node: (in): A #GbTreeNode.
+ * @node: A #GbTreeNode.
+ * @child: A #GbTreeNode.
  *
  * Prepends @child to the list of children owned by @node.
  */
@@ -168,7 +179,8 @@ gb_tree_node_prepend (GbTreeNode *node,
 
 /**
  * gb_tree_node_remove:
- * @node: (in): A #GbTreeNode.
+ * @node: A #GbTreeNode.
+ * @child: A #GbTreeNode.
  *
  * Removes @child from the list of children owned by @node.
  */
@@ -394,21 +406,24 @@ gb_tree_node_get_item (GbTreeNode *node)
   return node->item;
 }
 
-void
+gboolean
 gb_tree_node_expand (GbTreeNode *node,
                      gboolean    expand_ancestors)
 {
   GbTree *tree;
   GtkTreePath *path;
+  gboolean ret;
 
-  g_return_if_fail (GB_IS_TREE_NODE (node));
+  g_return_val_if_fail (GB_IS_TREE_NODE (node), FALSE);
 
   tree = gb_tree_node_get_tree (node);
   path = gb_tree_node_get_path (node);
-  gtk_tree_view_expand_row (GTK_TREE_VIEW (tree), path, FALSE);
+  ret = gtk_tree_view_expand_row (GTK_TREE_VIEW (tree), path, FALSE);
   if (expand_ancestors)
     gtk_tree_view_expand_to_path (GTK_TREE_VIEW (tree), path);
   gtk_tree_path_free (path);
+
+  return ret;
 }
 
 void
diff --git a/src/tree/gb-tree-node.h b/src/tree/gb-tree-node.h
index 3af41e7..ff80224 100644
--- a/src/tree/gb-tree-node.h
+++ b/src/tree/gb-tree-node.h
@@ -44,7 +44,7 @@ void           gb_tree_node_set_icon_name         (GbTreeNode   *node,
                                                    const gchar  *icon_name);
 void           gb_tree_node_set_item              (GbTreeNode   *node,
                                                    GObject      *item);
-void           gb_tree_node_expand                (GbTreeNode   *node,
+gboolean       gb_tree_node_expand                (GbTreeNode   *node,
                                                    gboolean      expand_ancestors);
 void           gb_tree_node_collapse              (GbTreeNode   *node);
 void           gb_tree_node_select                (GbTreeNode   *node);
diff --git a/src/tree/gb-tree.c b/src/tree/gb-tree.c
index 60dc1f7..1c34400 100644
--- a/src/tree/gb-tree.c
+++ b/src/tree/gb-tree.c
@@ -1209,7 +1209,7 @@ _gb_tree_get_path (GbTree *self,
 
 /**
  * gb_tree_add_builder:
- * @tree: (in): A #GbTree.
+ * @self: (in): A #GbTree.
  * @builder: (in) (transfer full): A #GbTreeBuilder to add.
  *
  * Removes a builder from the tree.
@@ -1239,7 +1239,7 @@ gb_tree_add_builder (GbTree        *self,
 
 /**
  * gb_tree_remove_builder:
- * @tree: (in): A #GbTree.
+ * @self: (in): A #GbTree.
  * @builder: (in): A #GbTreeBuilder to remove.
  *
  * Removes a builder from the tree.
@@ -1290,7 +1290,7 @@ gb_tree_get_root (GbTree *self)
 
 /**
  * gb_tree_set_root:
- * @tree: (in): A #GbTree.
+ * @self: (in): A #GbTree.
  * @node: (in): A #GbTreeNode.
  *
  * Sets the root node of the #GbTree widget. This is used to build
@@ -1355,7 +1355,7 @@ gb_tree_rebuild (GbTree *self)
 /**
  * gb_tree_find_custom:
  * @self: A #GbTree
- * @equal_func: A #GEqualFunc
+ * @equal_func: (scope call): A #GEqualFunc
  * @key: the key for @equal_func
  *
  * Walks the entire tree looking for the first item that matches given
@@ -1388,6 +1388,15 @@ gb_tree_find_custom (GbTree     *self,
   return lookup.result;
 }
 
+/**
+ * gb_tree_find_item:
+ * @self: A #GbTree.
+ * @item: (allow-none): A #GObject or %NULL.
+ *
+ * Finds a #GbTreeNode with an item property matching @item.
+ *
+ * Returns: (transfer none) (nullable): A #GbTreeNode or %NULL.
+ */
 GbTreeNode *
 gb_tree_find_item (GbTree  *self,
                    GObject *item)
@@ -1472,7 +1481,7 @@ _gb_tree_invalidate (GbTree     *self,
  * gb_tree_find_child_node:
  * @self: A #GbTree
  * @node: A #GbTreeNode
- * @find_func: (call scope): A callback to locate the child
+ * @find_func: (scope call): A callback to locate the child
  * @user_data: user data for @find_func
  *
  * Searches through the direct children of @node for a matching child.
@@ -1578,15 +1587,17 @@ _gb_tree_get_iter (GbTree      *self,
 {
   GbTreePrivate *priv = gb_tree_get_instance_private (self);
   GtkTreePath *path;
-  gboolean ret;
+  gboolean ret = FALSE;
 
   g_return_val_if_fail (GB_IS_TREE (self), FALSE);
   g_return_val_if_fail (GB_IS_TREE_NODE (node), FALSE);
   g_return_val_if_fail (iter, FALSE);
 
-  path = gb_tree_node_get_path (node);
-  ret = gtk_tree_model_get_iter (GTK_TREE_MODEL (priv->store), iter, path);
-  gtk_tree_path_free (path);
+  if ((path = gb_tree_node_get_path (node)) != NULL)
+    {
+      ret = gtk_tree_model_get_iter (GTK_TREE_MODEL (priv->store), iter, path);
+      gtk_tree_path_free (path);
+    }
 
   return ret;
 }