[gexiv2/wip/phako/gi-docgen: 12/15] doc: Minor updates

[Jens Georg <jensgeorg src gnome org>]

commit 216e8f23f0185bf519735fae727d1a3870c29e4a
Author: Jens Georg <mail jensge org>
Date:   Wed May 26 15:03:46 2021 +0200

    doc: Minor updates

 gexiv2/gexiv2-preview-image.h | 36 ++++++++++++++++++++++++++++++++++++
 1 file changed, 36 insertions(+)
---
diff --git a/gexiv2/gexiv2-preview-image.h b/gexiv2/gexiv2-preview-image.h
index f051223..7e98873 100644
--- a/gexiv2/gexiv2-preview-image.h
+++ b/gexiv2/gexiv2-preview-image.h
@@ -41,6 +41,29 @@ typedef struct _GExiv2PreviewImagePrivate    GExiv2PreviewImagePrivate;
 
 G_DEFINE_AUTOPTR_CLEANUP_FUNC(GExiv2PreviewImage, g_object_unref)
 
+/**
+ * GExiv2PreviewImage:
+ *
+ * `GExiv2PreviewImage` is an accessor to the preview images contained in
+ * the image's metadata. This could be anything from a thumbnail to a
+ * full-sized camera development of a RAW image.
+ *
+ * The `GExiv2PreviewImage` is obtained by calling gexiv2_metadata_get_preview_image()
+ * with an instance of #GExiv2PreviewProperties that are describing the image
+ * to be fetched.
+ *
+ * ```c
+ * GExiv2PreviewProperties **properties, **it;
+ * properties = it = gexiv2_metadata_get_preview_properties(metadata);
+ *
+ * while (*it) {
+ *   preview_image = gexiv2_metadata_get_preview_image(metadata, *it);
+ *   it++;
+ * }
+ * ```
+ *
+ */
+
 struct _GExiv2PreviewImage
 {
        GObject parent_instance;
@@ -77,6 +100,9 @@ void                 gexiv2_preview_image_free                               
(GExiv2PreviewImage *self);
  * @self: An instance of #GExiv2PreviewImage
  * @size: (out) (skip): The size of the buffer holding the data
  *
+ * Get a pointer to the image data of the preview image. The returned data is
+ * owned by the preview image and must not be freed.
+ *
  * Returns: (transfer none) (array length=size): The raw image data
  */
 const guint8*  gexiv2_preview_image_get_data                   (GExiv2PreviewImage *self, guint32 *size);
@@ -85,6 +111,8 @@ const guint8*        gexiv2_preview_image_get_data                   (GExiv2PreviewImage 
*self, guint32
  * gexiv2_preview_image_get_mime_type:
  * @self: An instance of #GExiv2PreviewImage
  *
+ * Get the MIME type associated with the preview image.
+ *
  * Returns: (transfer none): The preview image's MIME type.
  */
 const gchar*   gexiv2_preview_image_get_mime_type              (GExiv2PreviewImage *self);
@@ -93,6 +121,8 @@ const gchar* gexiv2_preview_image_get_mime_type              (GExiv2PreviewImage *self);
  * gexiv2_preview_image_get_extension:
  * @self: An instance of #GExiv2PreviewImage
  *
+ * Get the file extension commonly associated with the preview image
+ *
  * Returns: (transfer none): The preview image's recommended file extension.
  */
 const gchar*   gexiv2_preview_image_get_extension              (GExiv2PreviewImage *self);
@@ -101,6 +131,8 @@ const gchar*        gexiv2_preview_image_get_extension              (GExiv2PreviewImage 
*self);
  * gexiv2_preview_image_get_width:
  * @self: An instance of #GExiv2PreviewImage
  *
+ * Get the width in pixels
+ *
  * Returns: The preview image's display width in pixels.
  */
 guint32                        gexiv2_preview_image_get_width                  (GExiv2PreviewImage *self);
@@ -109,6 +141,8 @@ guint32                     gexiv2_preview_image_get_width                  
(GExiv2PreviewImage *self);
  * gexiv2_preview_image_get_height:
  * @self: An instance of #GExiv2PreviewImage
  *
+ * Get the height in pixels
+ *
  * Returns: The preview image's display height in pixels.
  */
 guint32                        gexiv2_preview_image_get_height                 (GExiv2PreviewImage *self);
@@ -118,6 +152,8 @@ guint32                     gexiv2_preview_image_get_height                 
(GExiv2PreviewImage *self);
  * @self: An instance of #GExiv2PreviewImage
  * @path: (in): The file path to write the preview image to.
  *
+ * Write the preview image to a file in @path
+ *
  * Returns: The number of bytes written to the file.
  */
 glong                  gexiv2_preview_image_write_file                 (GExiv2PreviewImage *self, const 
gchar *path);