From 2191c6024a7ecf4bfd766c9fb9c9781f14dd82a6 Mon Sep 17 00:00:00 2001
From: Matthias Clasen <mclasen@redhat.com>
Date: Sun, 24 Sep 2023 22:38:39 -0400
Subject: [PATCH] docs: Move the tree SECTION

Move the content to the new data-structures.md file.

Helps: #3037
---
 docs/reference/glib/data-structures.md | 26 ++++++++++++++++++++-
 glib/gtree.c                           | 32 --------------------------
 2 files changed, 25 insertions(+), 33 deletions(-)

diff --git a/docs/reference/glib/data-structures.md b/docs/reference/glib/data-structures.md
index acac89093..d7fbd427a 100644
--- a/docs/reference/glib/data-structures.md
+++ b/docs/reference/glib/data-structures.md
@@ -11,7 +11,7 @@ SPDX-FileCopyrightText: 2020 Endless OS Foundation, LLC
 # Data Structures
 
 GLib includes a number of basic data sructures, such as arrays, linked lists, hash tables,
-queues, etc.
+queues, trees, etc.
 
 ## Arrays
 
@@ -368,3 +368,27 @@ the `_unlocked` suffix).
 In many cases, it may be more convenient to use [struct@GLib.ThreadPool] when you need to distribute work
 to a set of worker threads instead of using `GAsyncQueue` manually. `GThreadPool` uses a `GAsyncQueue`
 internally.
+
+## Binary Trees
+
+The [struct@GLib.Tree] structure and its associated functions provide a sorted collection of key/value
+pairs optimized for searching and traversing in order. This means that most of the operations (access,
+search, insertion, deletion, …) on `GTree` are O(log(n)) in average and O(n) in worst case for time
+complexity. But, note that maintaining a balanced sorted `GTree` of n elements is done in time O(n log(n)).
+
+To create a new `GTree` use [ctor@GLib.Tree.new].
+
+To insert a key/value pair into a `GTree` use [method@GLib.Tree.insert] (O(n log(n))).
+
+To remove a key/value pair use [method@GLib.Tree.remove] (O(n log(n))).
+
+To look up the value corresponding to a given key, use [method@GLib.Tree.lookup] and
+[method@GLib.Tree.lookup_extended].
+
+To find out the number of nodes in a `GTree`, use [method@GLib.Tree.nnodes].
+To get the height of a `GTree`, use [method@GLib.Tree.height].
+
+To traverse a `GTree`, calling a function for each node visited in
+the traversal, use [method@GLib.Tree.foreach].
+
+To destroy a `GTree`, use [method@GLib.Tree.destroy].
diff --git a/glib/gtree.c b/glib/gtree.c
index bfae6399d..1b63d10a9 100644
--- a/glib/gtree.c
+++ b/glib/gtree.c
@@ -36,38 +36,6 @@
 #include "gtestutils.h"
 #include "gslice.h"
 
-/**
- * SECTION:trees-binary
- * @title: Balanced Binary Trees
- * @short_description: a sorted collection of key/value pairs optimized
- *                     for searching and traversing in order
- *
- * The #GTree structure and its associated functions provide a sorted
- * collection of key/value pairs optimized for searching and traversing
- * in order. This means that most of the operations  (access, search,
- * insertion, deletion, ...) on #GTree are O(log(n)) in average and O(n)
- * in worst case for time complexity. But, note that maintaining a
- * balanced sorted #GTree of n elements is done in time O(n log(n)).
- *
- * To create a new #GTree use g_tree_new().
- *
- * To insert a key/value pair into a #GTree use g_tree_insert()
- * (O(n log(n))).
- *
- * To remove a key/value pair use g_tree_remove() (O(n log(n))).
- *
- * To look up the value corresponding to a given key, use
- * g_tree_lookup() and g_tree_lookup_extended().
- *
- * To find out the number of nodes in a #GTree, use g_tree_nnodes(). To
- * get the height of a #GTree, use g_tree_height().
- *
- * To traverse a #GTree, calling a function for each node visited in
- * the traversal, use g_tree_foreach().
- *
- * To destroy a #GTree, use g_tree_destroy().
- **/
-
 #define MAX_GTREE_HEIGHT 40
 /* G_MAXUINT nodes will be covered by tree height of log2(G_MAXUINT) + 2. */
 G_STATIC_ASSERT ((G_GUINT64_CONSTANT (1) << (MAX_GTREE_HEIGHT - 2)) >= G_MAXUINT);