Issue #10673: make clearer API docs for _id*() functions.

All the functions working with object's IDs are mostly internal. They
are still made public because they can be useful and are relevant in
specific use cases (i.e. using IDs to reference items in specific
widgets, such as drop-down lists, or when temporarily storing an item as
integer, etc.).
Yet it should be made clear that these usages are the exception rather
than the norm.

app/pdb/display-cmds.c

@@ -245,7 +245,8 @@ register_display_procs (GimpPDB *pdb)
                                "gimp-display-id-is-valid");
   gimp_procedure_set_static_help (procedure,
                                   "Returns TRUE if the display ID is valid.",
-                                  "This procedure checks if the given display ID is valid and refers to an existing display.",
+                                  "This procedure checks if the given display ID is valid and refers to an existing display.\n"
+                                  "Note: in most use cases, you should not use this function. If you got a [class@Gimp.Display] from the API, you should trust it is valid. This function is mostly for internal usage.",
                                   NULL);
   gimp_procedure_set_static_attribution (procedure,
                                          "Sven Neumann <sven@gimp.org>",

app/pdb/item-cmds.c

@@ -1068,8 +1068,9 @@ register_item_procs (GimpPDB *pdb)
   gimp_object_set_static_name (GIMP_OBJECT (procedure),
                                "gimp-item-id-is-valid");
   gimp_procedure_set_static_help (procedure,
-                                  "Returns TRUE if the item ID is valid.",
+                                  "Returns %TRUE if the item ID is valid.",
-                                  "This procedure checks if the given item ID is valid and refers to an existing item.",
+                                  "This procedure checks if the given item ID is valid and refers to an existing item.\n"
+                                  "Note: in most use cases, you should not use this function. If you got a [class@Gimp.Item] from the API, you should trust it is valid. This function is mostly for internal usage.",
                                   NULL);
   gimp_procedure_set_static_attribution (procedure,
                                          "Sven Neumann <sven@gimp.org>",
@@ -1098,7 +1099,8 @@ register_item_procs (GimpPDB *pdb)
                                "gimp-item-id-is-drawable");
   gimp_procedure_set_static_help (procedure,
                                   "Returns whether the item ID is a drawable.",
-                                  "This procedure returns TRUE if the specified item ID is a drawable.",
+                                  "This procedure returns %TRUE if the specified item ID is a drawable.\n"
+                                  "Note: in most use cases, you should not use this function. See [func.Item.id_is_layer] for a discussion on alternatives.",
                                   NULL);
   gimp_procedure_set_static_attribution (procedure,
                                          "Spencer Kimball & Peter Mattis",
@@ -1127,7 +1129,18 @@ register_item_procs (GimpPDB *pdb)
                                "gimp-item-id-is-layer");
   gimp_procedure_set_static_help (procedure,
                                   "Returns whether the item ID is a layer.",
-                                  "This procedure returns TRUE if the specified item ID is a layer.",
+                                  "This procedure returns %TRUE if the specified item ID is a layer.\n"
+                                  "Note: in most use cases, you should not use this function. If the goal is to verify the accurate type for a [class.Item], you should either use [method.Item.is_layer] or the specific type-checking methods for the used language.\n"
+                                  "For instance, in C:\n"
+                                  "```C\n"
+                                  "if (GIMP_IS_LAYER (item))\n"
+                                  "do_something ();\n"
+                                  "```\n"
+                                  "Or in the Python binding, you could run:\n"
+                                  "```py3\n"
+                                  "if isinstance(item, Gimp.Layer):\n"
+                                  "do_something()\n"
+                                  "```",
                                   NULL);
   gimp_procedure_set_static_attribution (procedure,
                                          "Spencer Kimball & Peter Mattis",
@@ -1156,7 +1169,8 @@ register_item_procs (GimpPDB *pdb)
                                "gimp-item-id-is-text-layer");
   gimp_procedure_set_static_help (procedure,
                                   "Returns whether the item ID is a text layer.",
-                                  "This procedure returns TRUE if the specified item ID is a text layer.",
+                                  "This procedure returns %TRUE if the specified item ID is a text layer.\n"
+                                  "Note: in most use cases, you should not use this function. See [func@Gimp.Item.id_is_layer] for a discussion on alternatives.",
                                   NULL);
   gimp_procedure_set_static_attribution (procedure,
                                          "Michael Natterer <mitch@gimp.org>",
@@ -1185,7 +1199,8 @@ register_item_procs (GimpPDB *pdb)
                                "gimp-item-id-is-group-layer");
   gimp_procedure_set_static_help (procedure,
                                   "Returns whether the item ID is a group layer.",
-                                  "This procedure returns TRUE if the specified item ID is a group layer.",
+                                  "This procedure returns %TRUE if the specified item ID is a group layer.\n"
+                                  "Note: in most use cases, you should not use this function. See [func@Gimp.Item.id_is_layer] for a discussion on alternatives.",
                                   NULL);
   gimp_procedure_set_static_attribution (procedure,
                                          "Jehan",
@@ -1214,7 +1229,8 @@ register_item_procs (GimpPDB *pdb)
                                "gimp-item-id-is-channel");
   gimp_procedure_set_static_help (procedure,
                                   "Returns whether the item ID is a channel.",
-                                  "This procedure returns TRUE if the specified item ID is a channel.",
+                                  "This procedure returns %TRUE if the specified item ID is a channel.\n"
+                                  "Note: in most use cases, you should not use this function. See [func.Item.id_is_layer] for a discussion on alternatives.",
                                   NULL);
   gimp_procedure_set_static_attribution (procedure,
                                          "Spencer Kimball & Peter Mattis",
@@ -1243,7 +1259,8 @@ register_item_procs (GimpPDB *pdb)
                                "gimp-item-id-is-layer-mask");
   gimp_procedure_set_static_help (procedure,
                                   "Returns whether the item ID is a layer mask.",
-                                  "This procedure returns TRUE if the specified item ID is a layer mask.",
+                                  "This procedure returns %TRUE if the specified item ID is a layer mask.\n"
+                                  "Note: in most use cases, you should not use this function. See [func.Item.id_is_layer] for a discussion on alternatives.",
                                   NULL);
   gimp_procedure_set_static_attribution (procedure,
                                          "Spencer Kimball & Peter Mattis",
@@ -1272,7 +1289,8 @@ register_item_procs (GimpPDB *pdb)
                                "gimp-item-id-is-path");
   gimp_procedure_set_static_help (procedure,
                                   "Returns whether the item ID is a path.",
-                                  "This procedure returns TRUE if the specified item ID is a path.",
+                                  "This procedure returns %TRUE if the specified item ID is a path.\n"
+                                  "Note: in most use cases, you should not use this function. See [func.Item.id_is_layer] for a discussion on alternatives.",
                                   NULL);
   gimp_procedure_set_static_attribution (procedure,
                                          "Spencer Kimball & Peter Mattis",
@@ -1301,7 +1319,8 @@ register_item_procs (GimpPDB *pdb)
                                "gimp-item-id-is-selection");
   gimp_procedure_set_static_help (procedure,
                                   "Returns whether the item ID is a selection.",
-                                  "This procedure returns TRUE if the specified item ID is a selection.",
+                                  "This procedure returns %TRUE if the specified item ID is a selection.\n"
+                                  "Note: in most use cases, you should not use this function. See [func.Item.id_is_layer] for a discussion on alternatives.",
                                   NULL);
   gimp_procedure_set_static_attribution (procedure,
                                          "Spencer Kimball & Peter Mattis",
@@ -1382,7 +1401,7 @@ register_item_procs (GimpPDB *pdb)
                                "gimp-item-is-group");
   gimp_procedure_set_static_help (procedure,
                                   "Returns whether the item is a group item.",
-                                  "This procedure returns TRUE if the specified item is a group item which can have children.",
+                                  "This procedure returns %TRUE if the specified item is a group item which can have children.",
                                   NULL);
   gimp_procedure_set_static_attribution (procedure,
                                          "Michael Natterer <mitch@gimp.org>",
@@ -1475,7 +1494,7 @@ register_item_procs (GimpPDB *pdb)
                                "gimp-item-get-expanded");
   gimp_procedure_set_static_help (procedure,
                                   "Returns whether the item is expanded.",
-                                  "This procedure returns TRUE if the specified item is expanded.",
+                                  "This procedure returns %TRUE if the specified item is expanded.",
                                   NULL);
   gimp_procedure_set_static_attribution (procedure,
                                          "Ell",

app/pdb/resource-cmds.c

@@ -605,7 +605,8 @@ register_resource_procs (GimpPDB *pdb)
                                "gimp-resource-id-is-valid");
   gimp_procedure_set_static_help (procedure,
                                   "Returns TRUE if the resource ID is valid.",
-                                  "This procedure checks if the given resource ID is valid and refers to an existing resource.",
+                                  "This procedure checks if the given resource ID is valid and refers to an existing resource.\n"
+                                  "Note: in most use cases, you should not use this function. If you got a [class@Gimp.Resource] from the API, you should trust it is valid. This function is mostly for internal usage.",
                                   NULL);
   gimp_procedure_set_static_attribution (procedure,
                                          "Michael Natterer <mitch@gimp.org>",

libgimp/gimpdisplay.c

@@ -132,6 +132,9 @@ gimp_display_get_property (GObject    *object,
  * gimp_display_get_id:
  * @display: The display.
  *
+ * Note: in most use cases, you should not need a display's ID which is
+ * mostly internal data and not reusable across sessions.
+ *
  * Returns: the display ID.
  *
  * Since: 3.0
@@ -148,6 +151,11 @@ gimp_display_get_id (GimpDisplay *display)
  *
  * Returns a #GimpDisplay representing @display_id.
  *
+ * Note: in most use cases, you should not need to retrieve a
+ * #GimpDisplay by its ID, which is mostly internal data and not
+ * reusable across sessions. Use the appropriate functions for your use
+ * case instead.
+ *
  * Returns: (nullable) (transfer none): a #GimpDisplay for @display_id or
  *          %NULL if @display_id does not represent a valid display.
  *          The object belongs to libgimp and you must not modify or

libgimp/gimpdisplay_pdb.c

@@ -44,6 +44,9 @@
  *
  * This procedure checks if the given display ID is valid and refers to
  * an existing display.
+ * Note: in most use cases, you should not use this function. If you
+ * got a [class@Gimp.Display] from the API, you should trust it is
+ * valid. This function is mostly for internal usage.
  *
  * Returns: Whether the display ID is valid.
  *

libgimp/gimpitem.c

@@ -134,6 +134,9 @@ gimp_item_get_property (GObject    *object,
  * gimp_item_get_id:
  * @item: The item.
  *
+ * Note: in most use cases, you should not need an item's ID which is
+ * mostly internal data and not reusable across sessions.
+ *
  * Returns: the item ID.
  *
  * Since: 3.0
@@ -161,6 +164,10 @@ gimp_item_get_id (GimpItem *item)
  * abstract class, the real object type will actually be the proper
  * subclass.
  *
+ * Note: in most use cases, you should not need to retrieve a #GimpItem
+ * by its ID, which is mostly internal data and not reusable across
+ * sessions. Use the appropriate functions for your use case instead.
+ *
  * Returns: (nullable) (transfer none): a #GimpItem for @item_id or
  *          %NULL if @item_id does not represent a valid item.
  *          The object belongs to libgimp and you must not modify

libgimp/gimpitem_pdb.c

@@ -40,10 +40,13 @@
  * gimp_item_id_is_valid:
  * @item_id: The item ID to check.
  *
- * Returns TRUE if the item ID is valid.
+ * Returns %TRUE if the item ID is valid.
  *
  * This procedure checks if the given item ID is valid and refers to an
  * existing item.
+ * Note: in most use cases, you should not use this function. If you
+ * got a [class@Gimp.Item] from the API, you should trust it is valid.
+ * This function is mostly for internal usage.
  *
  * Returns: Whether the item ID is valid.
  *
@@ -79,7 +82,9 @@ gimp_item_id_is_valid (gint item_id)
  *
  * Returns whether the item ID is a drawable.
  *
- * This procedure returns TRUE if the specified item ID is a drawable.
+ * This procedure returns %TRUE if the specified item ID is a drawable.
+ * Note: in most use cases, you should not use this function. See
+ * [func.Item.id_is_layer] for a discussion on alternatives.
  *
  * Returns: TRUE if the item ID is a drawable, FALSE otherwise.
  *
@@ -115,7 +120,21 @@ gimp_item_id_is_drawable (gint item_id)
  *
  * Returns whether the item ID is a layer.
  *
- * This procedure returns TRUE if the specified item ID is a layer.
+ * This procedure returns %TRUE if the specified item ID is a layer.
+ * Note: in most use cases, you should not use this function. If the
+ * goal is to verify the accurate type for a [class.Item], you should
+ * either use [method.Item.is_layer] or the specific type-checking
+ * methods for the used language.
+ * For instance, in C:
+ * ```C
+ * if (GIMP_IS_LAYER (item))
+ * do_something ();
+ * ```
+ * Or in the Python binding, you could run:
+ * ```py3
+ * if isinstance(item, Gimp.Layer):
+ * do_something()
+ * ```
  *
  * Returns: TRUE if the item is a layer, FALSE otherwise.
  *
@@ -151,8 +170,10 @@ gimp_item_id_is_layer (gint item_id)
  *
  * Returns whether the item ID is a text layer.
  *
- * This procedure returns TRUE if the specified item ID is a text
+ * This procedure returns %TRUE if the specified item ID is a text
  * layer.
+ * Note: in most use cases, you should not use this function. See
+ * [func@Gimp.Item.id_is_layer] for a discussion on alternatives.
  *
  * Returns: TRUE if the item is a text layer, FALSE otherwise.
  *
@@ -188,8 +209,10 @@ gimp_item_id_is_text_layer (gint item_id)
  *
  * Returns whether the item ID is a group layer.
  *
- * This procedure returns TRUE if the specified item ID is a group
+ * This procedure returns %TRUE if the specified item ID is a group
  * layer.
+ * Note: in most use cases, you should not use this function. See
+ * [func@Gimp.Item.id_is_layer] for a discussion on alternatives.
  *
  * Returns: TRUE if the item is a group layer, FALSE otherwise.
  *
@@ -225,7 +248,9 @@ gimp_item_id_is_group_layer (gint item_id)
  *
  * Returns whether the item ID is a channel.
  *
- * This procedure returns TRUE if the specified item ID is a channel.
+ * This procedure returns %TRUE if the specified item ID is a channel.
+ * Note: in most use cases, you should not use this function. See
+ * [func.Item.id_is_layer] for a discussion on alternatives.
  *
  * Returns: TRUE if the item ID is a channel, FALSE otherwise.
  *
@@ -261,8 +286,10 @@ gimp_item_id_is_channel (gint item_id)
  *
  * Returns whether the item ID is a layer mask.
  *
- * This procedure returns TRUE if the specified item ID is a layer
+ * This procedure returns %TRUE if the specified item ID is a layer
  * mask.
+ * Note: in most use cases, you should not use this function. See
+ * [func.Item.id_is_layer] for a discussion on alternatives.
  *
  * Returns: TRUE if the item ID is a layer mask, FALSE otherwise.
  *
@@ -298,7 +325,9 @@ gimp_item_id_is_layer_mask (gint item_id)
  *
  * Returns whether the item ID is a path.
  *
- * This procedure returns TRUE if the specified item ID is a path.
+ * This procedure returns %TRUE if the specified item ID is a path.
+ * Note: in most use cases, you should not use this function. See
+ * [func.Item.id_is_layer] for a discussion on alternatives.
  *
  * Returns: TRUE if the item ID is a path, FALSE otherwise.
  *
@@ -334,7 +363,10 @@ gimp_item_id_is_path (gint item_id)
  *
  * Returns whether the item ID is a selection.
  *
- * This procedure returns TRUE if the specified item ID is a selection.
+ * This procedure returns %TRUE if the specified item ID is a
+ * selection.
+ * Note: in most use cases, you should not use this function. See
+ * [func.Item.id_is_layer] for a discussion on alternatives.
  *
  * Returns: TRUE if the item ID is a selection, FALSE otherwise.
  *
@@ -445,7 +477,7 @@ gimp_item_delete (GimpItem *item)
  *
  * Returns whether the item is a group item.
  *
- * This procedure returns TRUE if the specified item is a group item
+ * This procedure returns %TRUE if the specified item is a group item
  * which can have children.
  *
  * Returns: TRUE if the item is a group, FALSE otherwise.
@@ -564,7 +596,7 @@ gimp_item_get_children (GimpItem *item,
  *
  * Returns whether the item is expanded.
  *
- * This procedure returns TRUE if the specified item is expanded.
+ * This procedure returns %TRUE if the specified item is expanded.
  *
  * Returns: TRUE if the item is expanded, FALSE otherwise.
  *

libgimp/gimpresource.c

@@ -278,6 +278,9 @@ gimp_resource_deserialize_create (GType     type,
  * gimp_resource_get_id:
  * @resource: The resource.
  *
+ * Note: in most use cases, you should not need a resource's ID which is
+ * mostly internal data and not reusable across sessions.
+ *
  * Returns: the resource ID.
  *
  * Since: 3.0
@@ -305,6 +308,11 @@ gimp_resource_get_id (GimpResource *resource)
  * abstract class, the real object type will actually be the proper
  * subclass.
  *
+ * Note: in most use cases, you should not need to retrieve a
+ * #GimpResource by its ID, which is mostly internal data and not
+ * reusable across sessions. Use the appropriate functions for your use
+ * case instead.
+ *
  * Returns: (nullable) (transfer none): a #GimpResource for @resource_id or
  *          %NULL if @resource_id does not represent a valid resource.
  *          The object belongs to libgimp and you must not modify

libgimp/gimpresource_pdb.c

@@ -133,6 +133,9 @@ _gimp_resource_get_by_identifiers (const gchar *type_name,
  *
  * This procedure checks if the given resource ID is valid and refers
  * to an existing resource.
+ * Note: in most use cases, you should not use this function. If you
+ * got a [class@Gimp.Resource] from the API, you should trust it is
+ * valid. This function is mostly for internal usage.
  *
  * Returns: Whether the resource ID is valid.
  *

pdb/groups/display.pdb

@@ -22,6 +22,10 @@ sub display_id_is_valid {
     $help = <<'HELP';
 This procedure checks if the given display ID is valid and refers to an
 existing display.
+
+Note: in most use cases, you should not use this function. If you got a
+[class@Gimp.Display] from the API, you should trust it is valid. This
+function is mostly for internal usage.
 HELP
 
     &neo_pdb_misc('2007', '3.0');

pdb/groups/item.pdb

@@ -17,11 +17,15 @@
 # "Perlized" from C source by Manish Singh <yosh@gimp.org>
 
 sub item_id_is_valid {
-    $blurb = 'Returns TRUE if the item ID is valid.';
+    $blurb = 'Returns %TRUE if the item ID is valid.';
 
     $help = <<'HELP';
 This procedure checks if the given item ID is valid and refers to an
 existing item.
+
+Note: in most use cases, you should not use this function. If you got a
+[class@Gimp.Item] from the API, you should trust it is valid. This
+function is mostly for internal usage.
 HELP
 
     &neo_pdb_misc('2007', '3.0');
@@ -52,7 +56,10 @@ sub item_id_is_drawable {
     $blurb = 'Returns whether the item ID is a drawable.';
 
     $help = <<HELP;
-This procedure returns TRUE if the specified item ID is a drawable.
+This procedure returns %TRUE if the specified item ID is a drawable.
+
+Note: in most use cases, you should not use this function. See
+[func@Gimp.Item.id_is_layer] for a discussion on alternatives.
 HELP
 
     &std_pdb_misc;
@@ -84,7 +91,33 @@ sub item_id_is_layer {
     $blurb = 'Returns whether the item ID is a layer.';
 
     $help = <<HELP;
-This procedure returns TRUE if the specified item ID is a layer.
+This procedure returns %TRUE if the specified item ID is a layer.
+
+Note: in most use cases, you should not use this function. If the goal
+is to verify the accurate type for a [class@Gimp.Item], you should
+either use [method@Gimp.Item.is_layer] or the specific type-checking
+methods for the used language.
+
+For instance, in C:
+
+```C
+
+if (GIMP_IS_LAYER (item))
+
+  do_something ();
+
+```
+
+Or in the Python binding, you could run:
+
+```py3
+
+if isinstance(item, Gimp.Layer):
+
+  do_something()
+
+```
+
 HELP
 
     &std_pdb_misc;
@@ -116,7 +149,10 @@ sub item_id_is_text_layer {
     $blurb = 'Returns whether the item ID is a text layer.';
 
     $help = <<'HELP';
-This procedure returns TRUE if the specified item ID is a text layer.
+This procedure returns %TRUE if the specified item ID is a text layer.
+
+Note: in most use cases, you should not use this function. See
+[func@Gimp.Item.id_is_layer] for a discussion on alternatives.
 HELP
 
     &mitch_pdb_misc('2010', '3.0');
@@ -148,7 +184,10 @@ sub item_id_is_group_layer {
     $blurb = 'Returns whether the item ID is a group layer.';
 
     $help = <<'HELP';
-This procedure returns TRUE if the specified item ID is a group layer.
+This procedure returns %TRUE if the specified item ID is a group layer.
+
+Note: in most use cases, you should not use this function. See
+[func@Gimp.Item.id_is_layer] for a discussion on alternatives.
 HELP
 
     &jehan_pdb_misc('2024', '3.0');
@@ -178,7 +217,10 @@ sub item_id_is_channel {
     $blurb = 'Returns whether the item ID is a channel.';
 
     $help = <<HELP;
-This procedure returns TRUE if the specified item ID is a channel.
+This procedure returns %TRUE if the specified item ID is a channel.
+
+Note: in most use cases, you should not use this function. See
+[func@Gimp.Item.id_is_layer] for a discussion on alternatives.
 HELP
 
     &std_pdb_misc;
@@ -210,7 +252,10 @@ sub item_id_is_layer_mask {
     $blurb = 'Returns whether the item ID is a layer mask.';
 
     $help = <<HELP;
-This procedure returns TRUE if the specified item ID is a layer mask.
+This procedure returns %TRUE if the specified item ID is a layer mask.
+
+Note: in most use cases, you should not use this function. See
+[func@Gimp.Item.id_is_layer] for a discussion on alternatives.
 HELP
 
     &std_pdb_misc;
@@ -242,7 +287,10 @@ sub item_id_is_selection {
     $blurb = 'Returns whether the item ID is a selection.';
 
     $help = <<HELP;
-This procedure returns TRUE if the specified item ID is a selection.
+This procedure returns %TRUE if the specified item ID is a selection.
+
+Note: in most use cases, you should not use this function. See
+[func@Gimp.Item.id_is_layer] for a discussion on alternatives.
 HELP
 
     &std_pdb_misc;
@@ -274,7 +322,10 @@ sub item_id_is_path {
     $blurb = 'Returns whether the item ID is a path.';
 
     $help = <<HELP;
-This procedure returns TRUE if the specified item ID is a path.
+This procedure returns %TRUE if the specified item ID is a path.
+
+Note: in most use cases, you should not use this function. See
+[func@Gimp.Item.id_is_layer] for a discussion on alternatives.
 HELP
 
     &std_pdb_misc;
@@ -367,7 +418,7 @@ sub item_is_group {
     $blurb = 'Returns whether the item is a group item.';
 
     $help = <<HELP;
-This procedure returns TRUE if the specified item is a group item which
+This procedure returns %TRUE if the specified item is a group item which
 can have children.
 HELP
 
@@ -478,7 +529,7 @@ sub item_get_expanded {
     $blurb = 'Returns whether the item is expanded.';
 
     $help = <<HELP;
-This procedure returns TRUE if the specified item is expanded.
+This procedure returns %TRUE if the specified item is expanded.
 HELP
 
     &ell_pdb_misc('2017', '2.10');

pdb/groups/resource.pdb

@@ -107,6 +107,10 @@ sub resource_id_is_valid {
     $help = <<'HELP';
 This procedure checks if the given resource ID is valid and refers to an
 existing resource.
+
+Note: in most use cases, you should not use this function. If you got a
+[class@Gimp.Resource] from the API, you should trust it is valid. This
+function is mostly for internal usage.
 HELP
 
     &mitch_pdb_misc('2023', '3.0');