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

@@ -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.",
+                                  "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.\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,

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
+ * This procedure returns the list of root layers contained in the
- * image. The order of layers is from topmost to bottommost.
+ * 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.

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 = (