app, libgimp, pdb: improve Image class API docs

This mostly turns references into clickable links in the online
documentation for the Image class.

app/pdb/file-cmds.c

@@ -396,7 +396,7 @@ register_file_procs (GimpPDB *pdb)
                                "gimp-file-load");
   gimp_procedure_set_static_help (procedure,
                                   "Loads an image file by invoking the right load handler.",
-                                  "This procedure invokes the correct file load handler using magic if possible, and falling back on the file's extension and/or prefix if not.",
+                                  "This procedure invokes the correct file load handler using magic if possible, and falling back on the file's extension and/or prefix if not. Note that the loaded image will be marked as dirty, which can be changed by calling [method@Gimp.Image.clean_all].",
                                   NULL);
   gimp_procedure_set_static_attribution (procedure,
                                          "Josh MacDonald",

app/pdb/image-cmds.c

@@ -3086,9 +3086,9 @@ register_image_procs (GimpPDB *pdb)
                                "gimp-image-new");
   gimp_procedure_set_static_help (procedure,
                                   "Creates a new image with the specified width, height, and type.",
-                                  "Creates a new image, undisplayed, with the specified extents and type. A layer should be created and added before this image is displayed, or subsequent calls to 'gimp-display-new' with this image as an argument will fail. Layers can be created using the 'gimp-layer-new' commands. They can be added to an image using the 'gimp-image-insert-layer' command.\n"
+                                  "Creates a new image, undisplayed, with the specified extents and type. A layer should be created and added before this image is displayed, or subsequent calls to [ctor@Gimp.Display.new] with this image as an argument will fail. Layers can be created using the [ctor@Gimp.Layer.new] command. They can be added to an image using the [method@Gimp.Image.insert_layer] command.\n"
                                   "\n"
-                                  "If your image's type if INDEXED, a palette must also be set with [method@Gimp.Image.set_palette]. An indexed image without a palette will output unexpected colors.",
+                                  "If your image's type is INDEXED, a palette must also be set with [method@Gimp.Image.set_palette]. An indexed image without a palette will output unexpected colors.",
                                   NULL);
   gimp_procedure_set_static_attribution (procedure,
                                          "Spencer Kimball & Peter Mattis",
@@ -3130,7 +3130,7 @@ register_image_procs (GimpPDB *pdb)
                                "gimp-image-new-with-precision");
   gimp_procedure_set_static_help (procedure,
                                   "Creates a new image with the specified width, height, type and precision.",
-                                  "Creates a new image, undisplayed with the specified extents, type and precision. Indexed images can only be created at GIMP_PRECISION_U8_NON_LINEAR precision. See 'gimp-image-new' for further details.",
+                                  "Creates a new image, undisplayed with the specified extents, type and precision. Indexed images can only be created at [enum@Gimp.Precision.U8_NON_LINEAR] precision. See [ctor@Gimp.Image.new] for further details.",
                                   NULL);
   gimp_procedure_set_static_attribution (procedure,
                                          "Michael Natterer <mitch@gimp.org>",
@@ -3657,7 +3657,7 @@ register_image_procs (GimpPDB *pdb)
                                "gimp-image-insert-layer");
   gimp_procedure_set_static_help (procedure,
                                   "Add the specified layer to the image.",
-                                  "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 0, 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 0, then the layer is inserted above the active layer, or inside the group if the active layer is a layer group. 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 [method@Gimp.Item.is_group] and [ctor@Gimp.GroupLayer.new]) then the layer is added inside the group. If the parent is 0, 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 0, then the layer is inserted above the active layer, or inside the group if the active layer is a layer group. The layer type must be compatible with the image base type.",
                                   NULL);
   gimp_procedure_set_static_attribution (procedure,
                                          "Spencer Kimball & Peter Mattis",
@@ -3729,7 +3729,7 @@ register_image_procs (GimpPDB *pdb)
                                   "Freeze the image's layer list.",
                                   "This procedure freezes the layer list of the image, suppressing any updates to the Layers dialog in response to changes to the image's layers. This can significantly improve performance while applying changes affecting the layer list.\n"
                                   "\n"
-                                  "Each call to 'gimp-image-freeze-layers' should be matched by a corresponding call to 'gimp-image-thaw-layers', undoing its effects.",
+                                  "Each call to 'gimp-image-freeze-layers' should be matched by a corresponding call to [method@Gimp.Image.thaw_layers], undoing its effects.",
                                   NULL);
   gimp_procedure_set_static_attribution (procedure,
                                          "Ell",
@@ -3754,7 +3754,7 @@ register_image_procs (GimpPDB *pdb)
                                   "Thaw the image's layer list.",
                                   "This procedure thaws the layer list of the image, re-enabling updates to the Layers dialog.\n"
                                   "\n"
-                                  "This procedure should match a corresponding call to 'gimp-image-freeze-layers'.",
+                                  "This procedure should match a corresponding call to [method@Gimp.Image.freeze_layers].",
                                   NULL);
   gimp_procedure_set_static_attribution (procedure,
                                          "Ell",
@@ -3849,7 +3849,7 @@ register_image_procs (GimpPDB *pdb)
                                   "Freeze the image's channel list.",
                                   "This procedure freezes the channel list of the image, suppressing any updates to the Channels dialog in response to changes to the image's channels. This can significantly improve performance while applying changes affecting the channel list.\n"
                                   "\n"
-                                  "Each call to 'gimp-image-freeze-channels' should be matched by a corresponding call to 'gimp-image-thaw-channels', undoing its effects.",
+                                  "Each call to 'gimp-image-freeze-channels' should be matched by a corresponding call to [method@Gimp.Image.thaw_channels], undoing its effects.",
                                   NULL);
   gimp_procedure_set_static_attribution (procedure,
                                          "Ell",
@@ -3874,7 +3874,7 @@ register_image_procs (GimpPDB *pdb)
                                   "Thaw the image's channel list.",
                                   "This procedure thaws the channel list of the image, re-enabling updates to the Channels dialog.\n"
                                   "\n"
-                                  "This procedure should match a corresponding call to 'gimp-image-freeze-channels'.",
+                                  "This procedure should match a corresponding call to [method@Gimp.Image.freeze_channels].",
                                   NULL);
   gimp_procedure_set_static_attribution (procedure,
                                          "Ell",
@@ -4141,7 +4141,7 @@ register_image_procs (GimpPDB *pdb)
                                   "Freeze the image's path list.",
                                   "This procedure freezes the path list of the image, suppressing any updates to the Paths dialog in response to changes to the image's path. This can significantly improve performance while applying changes affecting the path list.\n"
                                   "\n"
-                                  "Each call to 'gimp-image-freeze-paths' should be matched by a corresponding call to gimp_image_thaw_paths (), undoing its effects.",
+                                  "Each call to 'gimp-image-freeze-paths' should be matched by a corresponding call to [method@Gimp.Image.thaw_paths], undoing its effects.",
                                   NULL);
   gimp_procedure_set_static_attribution (procedure,
                                          "Ell",
@@ -4166,7 +4166,7 @@ register_image_procs (GimpPDB *pdb)
                                   "Thaw the image's path list.",
                                   "This procedure thaws the path list of the image, re-enabling updates to the Paths dialog.\n"
                                   "\n"
-                                  "This procedure should match a corresponding call to 'gimp-image-freeze-paths'.",
+                                  "This procedure should match a corresponding call to [method@Gimp.Image.freeze_paths].",
                                   NULL);
   gimp_procedure_set_static_attribution (procedure,
                                          "Ell",
@@ -4385,7 +4385,7 @@ register_image_procs (GimpPDB *pdb)
                                "gimp-image-flatten");
   gimp_procedure_set_static_help (procedure,
                                   "Flatten all visible layers into a single layer. Discard all invisible layers.",
-                                  "This procedure combines the visible layers in a manner analogous to merging with the CLIP_TO_IMAGE merge type. Non-visible layers are discarded, and the resulting image is stripped of its alpha channel.",
+                                  "This procedure combines the visible layers in a manner analogous to merging with the [enum@Gimp.MergeType.CLIP_TO_IMAGE] merge type. Non-visible layers are discarded, and the resulting image is stripped of its alpha channel.",
                                   NULL);
   gimp_procedure_set_static_attribution (procedure,
                                          "Spencer Kimball & Peter Mattis",
@@ -4414,7 +4414,7 @@ register_image_procs (GimpPDB *pdb)
                                "gimp-image-merge-visible-layers");
   gimp_procedure_set_static_help (procedure,
                                   "Merge the visible image layers into one.",
-                                  "This procedure combines the visible layers into a single layer using the specified merge type. A merge type of EXPAND_AS_NECESSARY expands the final layer to encompass the areas of the visible layers. A merge type of CLIP_TO_IMAGE clips the final layer to the extents of the image. A merge type of CLIP_TO_BOTTOM_LAYER clips the final layer to the size of the bottommost layer.",
+                                  "This procedure combines the visible layers into a single layer using the specified merge type. A merge type of [enum@Gimp.MergeType.EXPAND_AS_NECESSARY] expands the final layer to encompass the areas of the visible layers. A merge type of [enum@Gimp.MergeType.CLIP_TO_IMAGE] clips the final layer to the extents of the image. A merge type of [enum@Gimp.MergeType.CLIP_TO_BOTTOM_LAYER] clips the final layer to the size of the bottommost layer.",
                                   NULL);
   gimp_procedure_set_static_attribution (procedure,
                                          "Spencer Kimball & Peter Mattis",
@@ -4452,7 +4452,7 @@ register_image_procs (GimpPDB *pdb)
                                "gimp-image-merge-down");
   gimp_procedure_set_static_help (procedure,
                                   "Merge the layer passed and the first visible layer below.",
-                                  "This procedure combines the passed layer and the first visible layer below it using the specified merge type. A merge type of EXPAND_AS_NECESSARY expands the final layer to encompass the areas of the visible layers. A merge type of CLIP_TO_IMAGE clips the final layer to the extents of the image. A merge type of CLIP_TO_BOTTOM_LAYER clips the final layer to the size of the bottommost layer.",
+                                  "This procedure combines the passed layer and the first visible layer below it using the specified merge type. A merge type of [enum@Gimp.MergeType.EXPAND_AS_NECESSARY] expands the final layer to encompass the areas of the visible layers. A merge type of [enum@Gimp.MergeType.CLIP_TO_IMAGE] clips the final layer to the extents of the image. A merge type of [enum@Gimp.MergeType.CLIP_TO_BOTTOM_LAYER] clips the final layer to the size of the bottommost layer.",
                                   NULL);
   gimp_procedure_set_static_attribution (procedure,
                                          "Larry Ewing",
@@ -4496,7 +4496,7 @@ register_image_procs (GimpPDB *pdb)
                                "gimp-image-get-palette");
   gimp_procedure_set_static_help (procedure,
                                   "Returns the image's colormap",
-                                  "This procedure returns the image's colormap as a %GimpPalette. If the image is not in Indexed color mode, %NULL is returned.",
+                                  "This procedure returns the image's colormap as a [class@Gimp.Palette]. If the image is not in Indexed color mode, %NULL is returned.",
                                   NULL);
   gimp_procedure_set_static_attribution (procedure,
                                          "Jehan",
@@ -4650,7 +4650,7 @@ register_image_procs (GimpPDB *pdb)
                                "gimp-image-is-dirty");
   gimp_procedure_set_static_help (procedure,
                                   "Checks if the image has unsaved changes.",
-                                  "This procedure checks the specified image's dirty count to see if it needs to be saved. Note that saving the image does not automatically set the dirty count to 0, you need to call 'gimp-image-clean-all' after calling a save procedure to make the image clean.",
+                                  "This procedure checks the specified image's dirty count to see if it needs to be saved. Note that saving the image does not automatically set the dirty count to 0, you need to call [method@Gimp.Image.clean_all] after calling a save procedure to make the image clean. When loading an image using e.g. [func@Gimp.file_load] the image will be marked as dirty too.",
                                   NULL);
   gimp_procedure_set_static_attribution (procedure,
                                          "Spencer Kimball & Peter Mattis",

libgimp/gimpfile_pdb.c

@@ -45,7 +45,8 @@
  *
  * This procedure invokes the correct file load handler using magic if
  * possible, and falling back on the file's extension and/or prefix if
- * not.
+ * not. Note that the loaded image will be marked as dirty, which can
+ * be changed by calling [method@Gimp.Image.clean_all].
  *
  * Returns: (transfer none): The output image.
  **/

libgimp/gimpimage_pdb.c

@@ -118,12 +118,12 @@ gimp_get_images (void)
  *
  * Creates a new image, undisplayed, with the specified extents and
  * type. A layer should be created and added before this image is
- * displayed, or subsequent calls to gimp_display_new() with this image
- * as an argument will fail. Layers can be created using the
- * gimp_layer_new() commands. They can be added to an image using the
- * gimp_image_insert_layer() command.
+ * displayed, or subsequent calls to [ctor@Gimp.Display.new] with this
+ * image as an argument will fail. Layers can be created using the
+ * [ctor@Gimp.Layer.new] command. They can be added to an image using
+ * the [method@Gimp.Image.insert_layer] command.
  *
- * If your image's type if INDEXED, a palette must also be set with
+ * If your image's type is INDEXED, a palette must also be set with
  * [method@Gimp.Image.set_palette]. An indexed image without a palette
  * will output unexpected colors.
  *
@@ -169,8 +169,8 @@ gimp_image_new (gint              width,
  *
  * Creates a new image, undisplayed with the specified extents, type
  * and precision. Indexed images can only be created at
- * GIMP_PRECISION_U8_NON_LINEAR precision. See gimp_image_new() for
- * further details.
+ * [enum@Gimp.Precision.U8_NON_LINEAR] precision. See
+ * [ctor@Gimp.Image.new] for further details.
  *
  * Returns: (transfer none): The newly created image.
  *
@@ -813,15 +813,15 @@ gimp_image_pick_correlate_layer (GimpImage *image,
  *
  * 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 0, 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 0, then the layer is inserted above the active layer,
- * or inside the group if the active layer is a layer group. The layer
- * type must be compatible with the image base type.
+ * [method@Gimp.Item.is_group] and [ctor@Gimp.GroupLayer.new]) then the
+ * layer is added inside the group. If the parent is 0, 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 0, then the layer is inserted above the
+ * active layer, or inside the group if the active layer is a layer
+ * group. The layer type must be compatible with the image base type.
  *
  * Returns: TRUE on success.
  **/
@@ -906,7 +906,8 @@ gimp_image_remove_layer (GimpImage *image,
  * changes affecting the layer list.
  *
  * Each call to gimp_image_freeze_layers() should be matched by a
- * corresponding call to gimp_image_thaw_layers(), undoing its effects.
+ * corresponding call to [method@Gimp.Image.thaw_layers], undoing its
+ * effects.
  *
  * Returns: TRUE on success.
  *
@@ -945,7 +946,7 @@ gimp_image_freeze_layers (GimpImage *image)
  * updates to the Layers dialog.
  *
  * This procedure should match a corresponding call to
- * gimp_image_freeze_layers().
+ * [method@Gimp.Image.freeze_layers].
  *
  * Returns: TRUE on success.
  *
@@ -1070,7 +1071,7 @@ gimp_image_remove_channel (GimpImage   *image,
  * applying changes affecting the channel list.
  *
  * Each call to gimp_image_freeze_channels() should be matched by a
- * corresponding call to gimp_image_thaw_channels(), undoing its
+ * corresponding call to [method@Gimp.Image.thaw_channels], undoing its
  * effects.
  *
  * Returns: TRUE on success.
@@ -1110,7 +1111,7 @@ gimp_image_freeze_channels (GimpImage *image)
  * updates to the Channels dialog.
  *
  * This procedure should match a corresponding call to
- * gimp_image_freeze_channels().
+ * [method@Gimp.Image.freeze_channels].
  *
  * Returns: TRUE on success.
  *
@@ -1433,7 +1434,8 @@ gimp_image_export_path_to_string (GimpImage *image,
  * changes affecting the path list.
  *
  * Each call to gimp_image_freeze_paths() should be matched by a
- * corresponding call to gimp_image_thaw_paths (), undoing its effects.
+ * corresponding call to [method@Gimp.Image.thaw_paths], undoing its
+ * effects.
  *
  * Returns: TRUE on success.
  *
@@ -1472,7 +1474,7 @@ gimp_image_freeze_paths (GimpImage *image)
  * to the Paths dialog.
  *
  * This procedure should match a corresponding call to
- * gimp_image_freeze_paths().
+ * [method@Gimp.Image.freeze_paths].
  *
  * Returns: TRUE on success.
  *
@@ -1762,8 +1764,9 @@ gimp_image_reorder_item (GimpImage *image,
  * invisible layers.
  *
  * This procedure combines the visible layers in a manner analogous to
- * merging with the CLIP_TO_IMAGE merge type. Non-visible layers are
- * discarded, and the resulting image is stripped of its alpha channel.
+ * merging with the [enum@Gimp.MergeType.CLIP_TO_IMAGE] merge type.
+ * Non-visible layers are discarded, and the resulting image is
+ * stripped of its alpha channel.
  *
  * Returns: (transfer none): The resulting layer.
  **/
@@ -1799,11 +1802,13 @@ gimp_image_flatten (GimpImage *image)
  * Merge the visible image layers into one.
  *
  * This procedure combines the visible layers into a single layer using
- * the specified merge type. A merge type of EXPAND_AS_NECESSARY
- * expands the final layer to encompass the areas of the visible
- * layers. A merge type of CLIP_TO_IMAGE clips the final layer to the
- * extents of the image. A merge type of CLIP_TO_BOTTOM_LAYER clips the
- * final layer to the size of the bottommost layer.
+ * the specified merge type. A merge type of
+ * [enum@Gimp.MergeType.EXPAND_AS_NECESSARY] expands the final layer to
+ * encompass the areas of the visible layers. A merge type of
+ * [enum@Gimp.MergeType.CLIP_TO_IMAGE] clips the final layer to the
+ * extents of the image. A merge type of
+ * [enum@Gimp.MergeType.CLIP_TO_BOTTOM_LAYER] clips the final layer to
+ * the size of the bottommost layer.
  *
  * Returns: (transfer none): The resulting layer.
  **/
@@ -1843,11 +1848,12 @@ gimp_image_merge_visible_layers (GimpImage     *image,
  *
  * This procedure combines the passed layer and the first visible layer
  * below it using the specified merge type. A merge type of
- * EXPAND_AS_NECESSARY expands the final layer to encompass the areas
- * of the visible layers. A merge type of CLIP_TO_IMAGE clips the final
- * layer to the extents of the image. A merge type of
- * CLIP_TO_BOTTOM_LAYER clips the final layer to the size of the
- * bottommost layer.
+ * [enum@Gimp.MergeType.EXPAND_AS_NECESSARY] expands the final layer to
+ * encompass the areas of the visible layers. A merge type of
+ * [enum@Gimp.MergeType.CLIP_TO_IMAGE] clips the final layer to the
+ * extents of the image. A merge type of
+ * [enum@Gimp.MergeType.CLIP_TO_BOTTOM_LAYER] clips the final layer to
+ * the size of the bottommost layer.
  *
  * Returns: (transfer none): The resulting layer.
  **/
@@ -1885,8 +1891,9 @@ gimp_image_merge_down (GimpImage     *image,
  *
  * Returns the image's colormap
  *
- * This procedure returns the image's colormap as a %GimpPalette. If
- * the image is not in Indexed color mode, %NULL is returned.
+ * This procedure returns the image's colormap as a
+ * [class@Gimp.Palette]. If the image is not in Indexed color mode,
+ * %NULL is returned.
  *
  * Returns: (transfer none): The image's colormap palette.
  *
@@ -2075,8 +2082,10 @@ gimp_image_clean_all (GimpImage *image)
  *
  * This procedure checks the specified image's dirty count to see if it
  * needs to be saved. Note that saving the image does not automatically
- * set the dirty count to 0, you need to call gimp_image_clean_all()
- * after calling a save procedure to make the image clean.
+ * set the dirty count to 0, you need to call
+ * [method@Gimp.Image.clean_all] after calling a save procedure to make
+ * the image clean. When loading an image using e.g.
+ * [func@Gimp.file_load] the image will be marked as dirty too.
  *
  * Returns: TRUE if the image has unsaved changes.
  **/

pdb/groups/file.pdb

@@ -23,7 +23,8 @@ sub file_load {
     $help = <<'HELP';
 This procedure invokes the correct file load handler using magic if
 possible, and falling back on the file's extension and/or prefix if
-not.
+not. Note that the loaded image will be marked as dirty, which can be
+changed by calling [method@Gimp.Image.clean_all].
 HELP
 
     &josh_pdb_misc('1997');

pdb/groups/image.pdb

@@ -82,13 +82,13 @@ sub image_new {
     $help = <<'HELP';
 Creates a new image, undisplayed, with the specified extents and
 type. A layer should be created and added before this image is
-displayed, or subsequent calls to gimp_display_new() with this image
-as an argument will fail. Layers can be created using the
-gimp_layer_new() commands. They can be added to an image using the
-gimp_image_insert_layer() command.
+displayed, or subsequent calls to [ctor@Gimp.Display.new] with this
+image as an argument will fail. Layers can be created using the
+[ctor@Gimp.Layer.new] command. They can be added to an image using the
+[method@Gimp.Image.insert_layer] command.
 
 
-If your image's type if INDEXED, a palette must also be set with
+If your image's type is INDEXED, a palette must also be set with
 [method@Gimp.Image.set_palette]. An indexed image without a palette will
 output unexpected colors.
 HELP
@@ -128,7 +128,7 @@ sub image_new_with_precision {
     $help = <<'HELP';
 Creates a new image, undisplayed with the specified extents, type and
 precision. Indexed images can only be created at
-GIMP_PRECISION_U8_NON_LINEAR precision. See gimp_image_new() for
+[enum@Gimp.Precision.U8_NON_LINEAR] precision. See [ctor@Gimp.Image.new] for
 further details.
 HELP
 
@@ -740,11 +740,11 @@ sub image_merge_visible_layers {
 
     $help = <<'HELP';
 This procedure combines the visible layers into a single layer using
-the specified merge type. A merge type of EXPAND_AS_NECESSARY expands
-the final layer to encompass the areas of the visible layers. A merge
-type of CLIP_TO_IMAGE clips the final layer to the extents of the
-image. A merge type of CLIP_TO_BOTTOM_LAYER clips the final layer to
-the size of the bottommost layer.
+the specified merge type. A merge type of [enum@Gimp.MergeType.EXPAND_AS_NECESSARY]
+expands the final layer to encompass the areas of the visible layers. A merge
+type of [enum@Gimp.MergeType.CLIP_TO_IMAGE] clips the final layer to the
+extents of the image. A merge type of [enum@Gimp.MergeType.CLIP_TO_BOTTOM_LAYER]
+clips the final layer to the size of the bottommost layer.
 HELP
 
     &std_pdb_misc;
@@ -790,11 +790,11 @@ sub image_merge_down {
     $help = <<'HELP';
 This procedure combines the passed layer and the first visible layer
 below it using the specified merge type. A merge type of
-EXPAND_AS_NECESSARY expands the final layer to encompass the areas of
-the visible layers. A merge type of CLIP_TO_IMAGE clips the final
-layer to the extents of the image. A merge type of
-CLIP_TO_BOTTOM_LAYER clips the final layer to the size of the
-bottommost layer.
+[enum@Gimp.MergeType.EXPAND_AS_NECESSARY] expands the final layer to encompass
+the areas of the visible layers. A merge type of
+[enum@Gimp.MergeType.CLIP_TO_IMAGE] clips the final layer to the extents of
+the image. A merge type of [enum@Gimp.MergeType.CLIP_TO_BOTTOM_LAYER] clips
+the final layer to the size of the bottommost layer.
 HELP
 
     &larry_pdb_misc('1998');
@@ -848,8 +848,8 @@ BLURB
 
     $help = <<'HELP';
 This procedure combines the visible layers in a manner analogous to merging
-with the CLIP_TO_IMAGE merge type. Non-visible layers are discarded, and the
-resulting image is stripped of its alpha channel.
+with the [enum@Gimp.MergeType.CLIP_TO_IMAGE] merge type. Non-visible layers
+are discarded, and the resulting image is stripped of its alpha channel.
 HELP
 
     &std_pdb_misc;
@@ -884,7 +884,7 @@ sub image_insert_layer {
     $help = <<'HELP';
 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
+[method@Gimp.Item.is_group] and [ctor@Gimp.GroupLayer.new]) then the layer is
 added inside the group. If the parent is 0, 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
@@ -978,7 +978,7 @@ changes affecting the layer list.
 
 
 Each call to gimp_image_freeze_layers() should be matched by a
-corresponding call to gimp_image_thaw_layers(), undoing its
+corresponding call to [method@Gimp.Image.thaw_layers], undoing its
 effects.
 HELP
 
@@ -1014,7 +1014,7 @@ updates to the Layers dialog.
 
 
 This procedure should match a corresponding call to
-gimp_image_freeze_layers().
+[method@Gimp.Image.freeze_layers].
 HELP
 
     &ell_pdb_misc('2018', '2.10.2');
@@ -1131,7 +1131,7 @@ changes affecting the channel list.
 
 
 Each call to gimp_image_freeze_channels() should be matched by a
-corresponding call to gimp_image_thaw_channels(), undoing its
+corresponding call to [method@Gimp.Image.thaw_channels], undoing its
 effects.
 HELP
 
@@ -1167,7 +1167,7 @@ updates to the Channels dialog.
 
 
 This procedure should match a corresponding call to
-gimp_image_freeze_channels().
+[method@Gimp.Image.freeze_channels].
 HELP
 
     @inargs = (
@@ -1486,7 +1486,7 @@ changes affecting the path list.
 
 
 Each call to gimp_image_freeze_paths() should be matched by a
-corresponding call to gimp_image_thaw_paths (), undoing its
+corresponding call to [method@Gimp.Image.thaw_paths], undoing its
 effects.
 HELP
 
@@ -1522,7 +1522,7 @@ updates to the Paths dialog.
 
 
 This procedure should match a corresponding call to
-gimp_image_freeze_paths().
+[method@Gimp.Image.freeze_paths].
 HELP
 
     @inargs = (
@@ -1636,7 +1636,7 @@ sub image_get_palette {
     $blurb = "Returns the image's colormap";
 
     $help = <<'HELP';
-This procedure returns the image's colormap as a %GimpPalette.
+This procedure returns the image's colormap as a [class@Gimp.Palette].
 If the image is not in Indexed color mode, %NULL is returned.
 HELP
 
@@ -1795,8 +1795,9 @@ sub image_is_dirty {
     $help = <<'HELP';
 This procedure checks the specified image's dirty count to see if it
 needs to be saved. Note that saving the image does not automatically
-set the dirty count to 0, you need to call gimp_image_clean_all() after
-calling a save procedure to make the image clean.
+set the dirty count to 0, you need to call [method@Gimp.Image.clean_all] after
+calling a save procedure to make the image clean. When loading an image using
+e.g. [func@Gimp.file_load] the image will be marked as dirty too.
 HELP
 
     &std_pdb_misc;