From 6dd48d1a82ce9ec877afccf8e4b657d7db551d01 Mon Sep 17 00:00:00 2001
From: Jehan <jehan@girinstud.io>
Date: Sun, 4 Apr 2021 00:02:19 +0200
Subject: [PATCH] app, libgimp, pdb: improve gimp_image_get_layers() docs.

I always found the docs misleading because when it says "Returns the
list of layers contained in the specified image", I really read "all the
layers, at any level", except it doesn't. It only returns the root
layers and it is up to the plug-in developer to loop through these if
one needs to go deeper.

So let's make the function docs clearer.
---
 app/pdb/image-cmds.c    |  7 ++++---
 libgimp/gimpimage_pdb.c | 14 ++++++++++----
 pdb/groups/image.pdb    | 13 ++++++++++---
 3 files changed, 24 insertions(+), 10 deletions(-)

diff --git a/app/pdb/image-cmds.c b/app/pdb/image-cmds.c
index 81a610d1d0..f3e91573e7 100644
--- a/app/pdb/image-cmds.c
+++ b/app/pdb/image-cmds.c
@@ -3266,8 +3266,9 @@ register_image_procs (GimpPDB *pdb)
   gimp_object_set_static_name (GIMP_OBJECT (procedure),
                                "gimp-image-get-layers");
   gimp_procedure_set_static_help (procedure,
-                                  "Returns the list of layers contained in the specified image.",
-                                  "This procedure returns the list of layers contained in the specified image. The order of layers is from topmost to bottommost.",
+                                  "Returns the list of root layers contained in the specified image.",
+                                  "This procedure returns the list of root layers contained in the specified image. The order of layers is from topmost to bottommost.\n"
+                                     "Note that this is not the full list of layers, but only the root layers, i.e. layers with no parents themselves. If you need all layers, it is up to you to verify that any of these layers is a group layer with 'gimp-item-is-group' and to obtain its children with 'gimp-item-get-children' (possibly recursively checking if these have children too).",
                                   NULL);
   gimp_procedure_set_static_attribution (procedure,
                                          "Spencer Kimball & Peter Mattis",
@@ -3282,7 +3283,7 @@ register_image_procs (GimpPDB *pdb)
   gimp_procedure_add_return_value (procedure,
                                    g_param_spec_int ("num-layers",
                                                      "num layers",
-                                                     "The number of layers contained in the image",
+                                                     "The number of root layers contained in the image",
                                                      0, G_MAXINT32, 0,
                                                      GIMP_PARAM_READWRITE));
   gimp_procedure_add_return_value (procedure,
diff --git a/libgimp/gimpimage_pdb.c b/libgimp/gimpimage_pdb.c
index 7999385334..44fd332c46 100644
--- a/libgimp/gimpimage_pdb.c
+++ b/libgimp/gimpimage_pdb.c
@@ -463,12 +463,18 @@ gimp_image_height (GimpImage *image)
 /**
  * gimp_image_get_layers:
  * @image: The image.
- * @num_layers: (out): The number of layers contained in the image.
+ * @num_layers: (out): The number of root layers contained in the image.
  *
- * Returns the list of layers contained in the specified image.
+ * Returns the list of root layers contained in the specified image.
  *
- * This procedure returns the list of layers contained in the specified
- * image. The order of layers is from topmost to bottommost.
+ * This procedure returns the list of root layers contained in the
+ * specified image. The order of layers is from topmost to bottommost.
+ * Note that this is not the full list of layers, but only the root
+ * layers, i.e. layers with no parents themselves. If you need all
+ * layers, it is up to you to verify that any of these layers is a
+ * group layer with gimp_item_is_group() and to obtain its children
+ * with gimp_item_get_children() (possibly recursively checking if
+ * these have children too).
  *
  * Returns: (array length=num_layers) (element-type GimpLayer) (transfer container):
  *          The list of layers contained in the image.
diff --git a/pdb/groups/image.pdb b/pdb/groups/image.pdb
index 24ef1d72d7..9b1ae0aea1 100644
--- a/pdb/groups/image.pdb
+++ b/pdb/groups/image.pdb
@@ -238,11 +238,18 @@ CODE
 }
 
 sub image_get_layers {
-    $blurb = 'Returns the list of layers contained in the specified image.';
+    $blurb = 'Returns the list of root layers contained in the specified image.';
 
     $help = <<HELP;
-This procedure returns the list of layers contained in the specified image.
+This procedure returns the list of root layers contained in the specified image.
 The order of layers is from topmost to bottommost.
+
+Note that this is not the full list of layers, but only the root layers,
+i.e. layers with no parents themselves. If you need all layers, it is up
+to you to verify that any of these layers is a group layer with
+gimp_item_is_group() and to obtain its children with
+gimp_item_get_children() (possibly recursively checking if these have
+children too).
 HELP
 
     &std_pdb_misc;
@@ -256,7 +263,7 @@ HELP
         { name => 'layers', type => 'layerarray',
           desc => 'The list of layers contained in the image.',
           array => { name => 'num_layers',
-                     desc => 'The number of layers contained in the image' } }
+                     desc => 'The number of root layers contained in the image' } }
     );
 
     %invoke = (