From 9e1d0d7642b80f11bdab0430e5f27b4f52837345 Mon Sep 17 00:00:00 2001
From: lloyd konneker <konnekerl@gmail.com>
Date: Tue, 19 Nov 2024 09:17:17 -0500
Subject: [PATCH] PDB: improve doc string for gimp-image-reorder-item

Discuss requirements on args.

Discuss reordering in a group versus moving to top-level.
---
 app/pdb/image-cmds.c    |  6 +++++-
 libgimp/gimpimage_pdb.c | 12 +++++++++++-
 pdb/groups/image.pdb    | 15 ++++++++++++++-
 3 files changed, 30 insertions(+), 3 deletions(-)

diff --git a/app/pdb/image-cmds.c b/app/pdb/image-cmds.c
index 59d85b38dc..4508ff7540 100644
--- a/app/pdb/image-cmds.c
+++ b/app/pdb/image-cmds.c
@@ -4340,7 +4340,11 @@ register_image_procs (GimpPDB *pdb)
                                "gimp-image-reorder-item");
   gimp_procedure_set_static_help (procedure,
                                   "Reorder the specified item within its item tree",
-                                  "This procedure reorders the specified item within its item tree.",
+                                  "Reorders or moves item within an item tree. Requires parent is %NULL or a GroupLayer, else returns error. When parent is not %NULL and item is in parent, reorders item within parent group. When parent is not %NULL and item is not in parent, moves item into parent group. When parent is %NULL, moves item from current parent to top level.\n"
+                                  "\n"
+                                  "Requires item is in same tree as not %NULL parent, else returns error. Layers, Channels, and Paths are in separate trees.\n"
+                                  "\n"
+                                  "Requires item is not ancestor of parent, else returns error, to preclude cycles.",
                                   NULL);
   gimp_procedure_set_static_attribution (procedure,
                                          "Michael Natterer <mitch@gimp.org>",
diff --git a/libgimp/gimpimage_pdb.c b/libgimp/gimpimage_pdb.c
index b54c76d7e4..f204c047d9 100644
--- a/libgimp/gimpimage_pdb.c
+++ b/libgimp/gimpimage_pdb.c
@@ -1709,7 +1709,17 @@ gimp_image_lower_item_to_bottom (GimpImage *image,
  *
  * Reorder the specified item within its item tree
  *
- * This procedure reorders the specified item within its item tree.
+ * Reorders or moves item within an item tree. Requires parent is %NULL
+ * or a GroupLayer, else returns error. When parent is not %NULL and
+ * item is in parent, reorders item within parent group. When parent is
+ * not %NULL and item is not in parent, moves item into parent group.
+ * When parent is %NULL, moves item from current parent to top level.
+ *
+ * Requires item is in same tree as not %NULL parent, else returns
+ * error. Layers, Channels, and Paths are in separate trees.
+ *
+ * Requires item is not ancestor of parent, else returns error, to
+ * preclude cycles.
  *
  * Returns: TRUE on success.
  *
diff --git a/pdb/groups/image.pdb b/pdb/groups/image.pdb
index 72b88f561b..cc4e9901e1 100644
--- a/pdb/groups/image.pdb
+++ b/pdb/groups/image.pdb
@@ -687,7 +687,20 @@ sub image_reorder_item {
     $blurb = "Reorder the specified item within its item tree";
 
     $help = <<'HELP';
-This procedure reorders the specified item within its item tree.
+Reorders or moves item within an item tree.
+Requires parent is %NULL or a GroupLayer, else returns error.
+When parent is not %NULL and item is in parent,
+reorders item within parent group.
+When parent is not %NULL and item is not in parent,
+moves item into parent group.
+When parent is %NULL, moves item from current parent to top level.
+
+
+Requires item is in same tree as not %NULL parent, else returns error.
+Layers, Channels, and Paths are in separate trees.
+
+
+Requires item is not ancestor of parent, else returns error, to preclude cycles.
 HELP
 
     &mitch_pdb_misc('2010', '2.8');