[gimp] pdb: Add a more detailed description to the gimp_image_insert functions

[Barak Itkin <barakitkin src gnome org>]

commit 2f62347bf61b74260cb44f98bf19d7263a00006d
Author: Barak Itkin <lightningismyname gmail com>
Date:   Wed Sep 15 00:02:28 2010 +0200

    pdb: Add a more detailed description to the gimp_image_insert functions

 app/pdb/image-cmds.c       |    6 +++---
 libgimp/gimpimage_pdb.c    |   24 +++++++++++++++++-------
 tools/pdbgen/pdb/image.pdb |   28 +++++++++++++++++++---------
 3 files changed, 39 insertions(+), 19 deletions(-)
---
diff --git a/app/pdb/image-cmds.c b/app/pdb/image-cmds.c
index 27aa086..940e21d 100644
--- a/app/pdb/image-cmds.c
+++ b/app/pdb/image-cmds.c
@@ -3744,7 +3744,7 @@ register_image_procs (GimpPDB *pdb)
   gimp_procedure_set_static_strings (procedure,
                                      "gimp-image-insert-layer",
                                      "Add the specified layer to the image.",
-                                     "This procedure adds the specified layer to the image at the given position. If the position is specified as -1 and the parent is specified as NULL, then the layer is inserted above the active layer. The layer type must be compatible with the image base type.",
+                                     "This procedure adds the specified layer to the image at the given position. If the specified parent is a valid layer group (See 'gimp-item-is-group' and 'gimp-layer-group-new') then the layer is added inside the group. If the parent is NULL, the layer is added inside the main stack, outside of any group. The position argument specifies the location of the layer inside the stack (or the group, if a valid parent was supplied), starting from the top (0) and increasing. If the position is specified as -1 and the parent is specified as NULL, then the layer is inserted above the active layer. The layer type must be compatible with the image base type.",
                                      "Spencer Kimball & Peter Mattis",
                                      "Spencer Kimball & Peter Mattis",
                                      "1995-1996",
@@ -3849,7 +3849,7 @@ register_image_procs (GimpPDB *pdb)
   gimp_procedure_set_static_strings (procedure,
                                      "gimp-image-insert-channel",
                                      "Add the specified channel to the image.",
-                                     "This procedure adds the specified channel to the image at the given position. If the position is specified as -1 and the parent is specified as NULL, then the channel is inserted above the active channel.",
+                                     "This procedure adds the specified channel to the image at the given position. Since channel groups are not currently supported, the parent argument must always be NULL. The position argument specifies the location of the channel inside the stack, starting from the top (0) and increasing. If the position is specified as -1, then the channel is inserted above the active channel.",
                                      "Spencer Kimball & Peter Mattis",
                                      "Spencer Kimball & Peter Mattis",
                                      "1995-1996",
@@ -3954,7 +3954,7 @@ register_image_procs (GimpPDB *pdb)
   gimp_procedure_set_static_strings (procedure,
                                      "gimp-image-insert-vectors",
                                      "Add the specified vectors to the image.",
-                                     "This procedure adds the specified vectors to the image at the given position. If the position is specified as -1 and the parent is specified as NULL, then the vectors is inserted above the active vectors.",
+                                     "This procedure adds the specified vectors to the image at the given position. Since vectors groups are not currently supported, the parent argument must always be NULL. The position argument specifies the location of the vectors inside the stack, starting from the top (0) and increasing. If the position is specified as -1, then the vectors is inserted above the active vectors.",
                                      "Spencer Kimball & Peter Mattis",
                                      "Spencer Kimball & Peter Mattis",
                                      "1995-1996",
diff --git a/libgimp/gimpimage_pdb.c b/libgimp/gimpimage_pdb.c
index 2541e06..9b288ea 100644
--- a/libgimp/gimpimage_pdb.c
+++ b/libgimp/gimpimage_pdb.c
@@ -1011,7 +1011,13 @@ gimp_image_add_layer (gint32 image_ID,
  * Add the specified layer to the image.
  *
  * This procedure adds the specified layer to the image at the given
- * position. If the position is specified as -1 and the parent is
+ * position. If the specified parent is a valid layer group (See
+ * gimp_item_is_group() and gimp_layer_group_new()) then the layer is
+ * added inside the group. If the parent is NULL, the layer is added
+ * inside the main stack, outside of any group. The position argument
+ * specifies the location of the layer inside the stack (or the group,
+ * if a valid parent was supplied), starting from the top (0) and
+ * increasing. If the position is specified as -1 and the parent is
  * specified as NULL, then the layer is inserted above the active
  * layer. The layer type must be compatible with the image base type.
  *
@@ -1121,9 +1127,11 @@ gimp_image_add_channel (gint32 image_ID,
  * Add the specified channel to the image.
  *
  * This procedure adds the specified channel to the image at the given
- * position. If the position is specified as -1 and the parent is
- * specified as NULL, then the channel is inserted above the active
- * channel.
+ * position. Since channel groups are not currently supported, the
+ * parent argument must always be NULL. The position argument specifies
+ * the location of the channel inside the stack, starting from the top
+ * (0) and increasing. If the position is specified as -1, then the
+ * channel is inserted above the active channel.
  *
  * Returns: TRUE on success.
  */
@@ -1228,9 +1236,11 @@ gimp_image_add_vectors (gint32 image_ID,
  * Add the specified vectors to the image.
  *
  * This procedure adds the specified vectors to the image at the given
- * position. If the position is specified as -1 and the parent is
- * specified as NULL, then the vectors is inserted above the active
- * vectors.
+ * position. Since vectors groups are not currently supported, the
+ * parent argument must always be NULL. The position argument specifies
+ * the location of the vectors inside the stack, starting from the top
+ * (0) and increasing. If the position is specified as -1, then the
+ * vectors is inserted above the active vectors.
  *
  * Returns: TRUE on success.
  */
diff --git a/tools/pdbgen/pdb/image.pdb b/tools/pdbgen/pdb/image.pdb
index 95ec2ea..57d03ca 100644
--- a/tools/pdbgen/pdb/image.pdb
+++ b/tools/pdbgen/pdb/image.pdb
@@ -1196,9 +1196,15 @@ sub image_insert_layer {
 
     $help = <<'HELP';
 This procedure adds the specified layer to the image at the given
-position.  If the position is specified as -1 and the parent is
-specified as NULL, then the layer is inserted above the active
-layer. The layer type must be compatible with the image base type.
+position. If the specified parent is a valid layer group (See
+gimp_item_is_group() and gimp_layer_group_new()) then the layer is
+added inside the group. If the parent is NULL, the layer is added
+inside the main stack, outside of any group. The position argument
+specifies the location of the layer inside the stack (or the group, if
+a valid parent was supplied), starting from the top (0) and increasing.
+If the position is specified as -1 and the parent is specified as NULL,
+then the layer is inserted above the active layer. The layer type must
+be compatible with the image base type.
 HELP
 
     &std_pdb_misc;
@@ -1428,9 +1434,11 @@ sub image_insert_channel {
 
     $help = <<'HELP';
 This procedure adds the specified channel to the image at the given
-position.  If the position is specified as -1 and the parent is
-specified as NULL, then the channel is inserted above the active
-channel.
+position. Since channel groups are not currently supported, the parent
+argument must always be NULL. The position argument specifies the
+location of the channel inside the stack, starting from the top (0) and
+increasing. If the position is specified as -1, then the channel is
+inserted above the active channel.
 HELP
 
     &std_pdb_misc;
@@ -1528,9 +1536,11 @@ sub image_insert_vectors {
 
     $help = <<'HELP';
 This procedure adds the specified vectors to the image at the given
-position.  If the position is specified as -1 and the parent is
-specified as NULL, then the vectors is inserted above the active
-vectors.
+position. Since vectors groups are not currently supported, the parent
+argument must always be NULL. The position argument specifies the
+location of the vectors inside the stack, starting from the top (0) and
+increasing. If the position is specified as -1, then the vectors is
+inserted above the active vectors.
 HELP
 
     &std_pdb_misc;