[gimp] libgimp: improve docs for gimp_image_metadata_save_prepare()/finish()

[Michael Natterer <mitch src gnome org>]

commit 7f2995d568030b6107ad59dd2c3394b8a783730b
Author: Michael Natterer <mitch gimp org>
Date:   Thu Oct 10 00:05:49 2019 +0200

    libgimp: improve docs for gimp_image_metadata_save_prepare()/finish()

 libgimp/gimpimagemetadata-save.c | 14 +++++++++-----
 1 file changed, 9 insertions(+), 5 deletions(-)
---
diff --git a/libgimp/gimpimagemetadata-save.c b/libgimp/gimpimagemetadata-save.c
index 4ab03a78e7..5034fdc400 100644
--- a/libgimp/gimpimagemetadata-save.c
+++ b/libgimp/gimpimagemetadata-save.c
@@ -42,7 +42,7 @@ typedef struct
 
 /**
  * gimp_image_metadata_save_prepare:
- * @image:           The image
+ * @image:           The original image
  * @mime_type:       The saved file's mime-type
  * @suggested_flags: Suggested default values for the @flags passed to
  *                   gimp_image_metadata_save_finish()
@@ -59,7 +59,7 @@ typedef struct
  * override the preferences without a good reason since it is a data
  * leak.
  *
- * The suggested value for GIMP_METADATA_SAVE_THUMBNAIL is determined by
+ * The suggested value for %GIMP_METADATA_SAVE_THUMBNAIL is determined by
  * whether there was a thumbnail in the previously imported image.
  *
  * Returns: (transfer full): The image's metadata, prepared for saving.
@@ -261,17 +261,21 @@ gimp_image_metadata_copy_tag (GExiv2Metadata *src,
 
 /**
  * gimp_image_metadata_save_finish:
- * @image:     The image
+ * @image:     The actually saved image
  * @mime_type: The saved file's mime-type
- * @metadata:  The metadata to set on the image
+ * @metadata:  The metadata to write to @file
  * @flags:     Flags to specify what of the metadata to save
- * @file:      The file to load the metadata from
+ * @file:      The file @image was saved to
  * @error:     Return location for error message
  *
  * Saves the @metadata retrieved from the image with
  * gimp_image_metadata_save_prepare() to @file, taking into account
  * the passed @flags.
  *
+ * Note that the @image passed to this function might be different
+ * from the image passed to gimp_image_metadata_save_prepare(), due
+ * to whatever file export conversion happened in the meantime
+ *
  * Returns: Whether the save was successful.
  *
  * Since: 2.10