GNOME.org
 

[gexiv2/wip/phako/gi-docgen: 15/15] Some documentation fixes


commit 836e39f09ecd005fb3c285325afe95d90ccf7262
Author: Jens Georg <mail jensge org>
Date:   Sun Jun 20 15:22:54 2021 +0200

    Some documentation fixes

 gexiv2/gexiv2-metadata.h | 120 ++++++++++++++++++++++++++++++-----------------
 gexiv2/meson.build       |   1 +
 2 files changed, 77 insertions(+), 44 deletions(-)
---
diff --git a/gexiv2/gexiv2-metadata.h b/gexiv2/gexiv2-metadata.h
index c8b225e..3890374 100644
--- a/gexiv2/gexiv2-metadata.h
+++ b/gexiv2/gexiv2-metadata.h
@@ -17,18 +17,6 @@
 #include <gexiv2/gexiv2-preview-properties.h>
 #include <gexiv2/gexiv2-preview-image.h>
 
-/**
- * SECTION: gexiv2-metadata
- * @title: Generic image metadata handling
- * @short_description: Class to handle the various image metadata standards
- * @include: gexiv2/gexiv2.h
- *
- * #GExiv2Metadata is a generic object that provides everything from simple
- * aggregated accessors to common data such as image comments up to
- * fine-grained access to specific tags of a specific format, be it EXIF, IPTC
- * or XMP
- */
-
 /**
  * SECTION: gexiv2-metadata-xmp
  * @short_description: Functionality specific to the XMP familiy of metadata information
@@ -233,19 +221,22 @@ typedef enum {
 /**
  * GExiv2Metadata:
  *
- * An object holding all the Exiv2 metadata.  Previews, if present, are also available.
+ * An object holding all the Exiv2 metadata. Previews, if present, are also available.
+ *
+ * It is a generic object that provides everything from simple aggregated accessors
+ * to common data such as image comments up to fine-grained access to specific tags of a
+ * specfic format, be it EXIF, IPTC or XMP.
  *
  * As gexiv2 is only a wrapper around Exiv2, it's better to read its documentation to understand
- * the full scope of what it offers: <ulink url="http://www.exiv2.org/";></ulink>
+ * the full scope of what it offers: <http://www.exiv2.org/>
  *
  * In particular, rather than providing a getter/setter method pair for every metadata value
  * available for images (of which there are thousands), Exiv2 uses a dotted addressing scheme.
  * For example, to access a photo's EXIF Orientation field, the caller passes to Exiv2
- * "Exif.Photo.Orientation".  These <emphasis>tags</emphasis> (in Exiv2 parlance) are key to using Exiv2 (and
+ * "Exif.Photo.Orientation".  These *tags* (in Exiv2 parlance) are key to using Exiv2 (and
  * therefore gexiv2) to its fullest.
  *
- * A full reference for all supported Exiv2 tags can be found at
- * <ulink url="http://www.exiv2.org/metadata.html";></ulink>
+ * A full reference for all supported Exiv2 tags can be found at <http://www.exiv2.org/metadata.html>
  */
 typedef struct _GExiv2Metadata                 GExiv2Metadata;
 typedef struct _GExiv2MetadataClass            GExiv2MetadataClass;
@@ -273,6 +264,12 @@ GType                      gexiv2_metadata_get_type                        (void);
 /**
  * gexiv2_metadata_new:
  *
+ * Create an empty Metadata object.
+ *
+ * To use it, either use the many setter functions to popuplate the data from
+ * scratch or use [method@GExiv2.Metadata.open_path] or
+ * [method@GExiv2.Metadata.open_buf] to populate it from an existing file.
+ *
  * Returns: (transfer full): A fully constructed #GExiv2Metadata ready to be used
  */
 GExiv2Metadata* gexiv2_metadata_new                                    (void);
@@ -294,7 +291,10 @@ void                       gexiv2_metadata_free                            
(GExiv2Metadata *self);
  * @path: Path to the file you want to open
  * @error: (allow-none): A return location for a #GError or %NULL
  *
- * The file must be an image format supported by Exiv2.
+ * Populate metadata from @path.
+ *
+ * The file must be an image format supported by Exiv2. If called multiple times,
+ * current metadata will be replaced by the content of the last file opened.
  *
  * Returns: Boolean success indicator
  */
@@ -307,7 +307,10 @@ gboolean           gexiv2_metadata_open_path                       (GExiv2Metadata 
*self, const gchar *path,
  * @n_data: (skip): The length of the buffer
  * @error: (allow-none): A return location for a #GError or %NULL
  *
- * The buffer must be an image format supported by Exiv2.
+ * Populate metadata from a memory buffer.
+ *
+ * The buffer must be an image format supported by Exiv2. If called multiple times,
+ * current metadata will be replaced by the content of the last file opened.
  *
  * Returns: Boolean success indicator
  */
@@ -319,6 +322,9 @@ gboolean            gexiv2_metadata_open_buf                        (GExiv2Metadata 
*self, const guint8 *data,
  * @cb: A #ManagedStreamCallbacks struct offering stream access.
  * @error: (allow-none): A return location for a #GError or %NULL
  *
+ * Use a set of callbacks (see `ManagedStreamCallbacks`) to provide a file-like
+ * interface that can be used to feed arbitrary elements into the library.
+ *
  * The stream must be an image format supported by Exiv2.
  *
  * Returns: Boolean success indicator
@@ -394,9 +400,11 @@ gboolean           gexiv2_metadata_save_stream                     (GExiv2Metadata 
*self, ManagedStreamCall
  * @self: An instance of #GExiv2Metadata
  * @tag: Exiv2 tag
  *
- * The Exiv2 Tag Reference can be found at <ulink url="http://exiv2.org/metadata.html";></ulink>
+ * Check for presence of a tag.
+ *
+ * The Exiv2 Tag Reference can be found at <http://exiv2.org/metadata.html>
  *
- * Returns: TRUE if the tag is present.
+ * Returns: %TRUE if the tag is present.
  */
 gboolean               gexiv2_metadata_has_tag                         (GExiv2Metadata *self, const gchar* 
tag);
 
@@ -407,9 +415,9 @@ gboolean            gexiv2_metadata_has_tag                         (GExiv2Metadata 
*self, const gchar* tag);
  *
  * Removes the Exiv2 tag from the metadata object.
  *
- * The Exiv2 Tag Reference can be found at <ulink url="http://exiv2.org/metadata.html";></ulink>
+ * The Exiv2 Tag Reference can be found at <http://exiv2.org/metadata.html>
  *
- * Returns: TRUE if the tag was present.
+ * Returns: %TRUE if the tag was present.
  */
 gboolean               gexiv2_metadata_clear_tag                       (GExiv2Metadata *self, const gchar* 
tag);
 
@@ -425,7 +433,9 @@ void                        gexiv2_metadata_clear                           
(GExiv2Metadata *self);
  * gexiv2_metadata_is_exif_tag:
  * @tag: An Exiv2 tag
  *
- * The Exiv2 Tag Reference can be found at <ulink url="http://exiv2.org/metadata.html";></ulink>
+ * Check whether @tag is from the EXIF domain of tags.
+ *
+ * The Exiv2 Tag Reference can be found at <http://exiv2.org/metadata.html>
  *
  * Returns: TRUE if the Exiv2 tag is for the EXIF domain.
  */
@@ -435,7 +445,9 @@ gboolean            gexiv2_metadata_is_exif_tag                             (const gchar* 
tag);
  * gexiv2_metadata_is_iptc_tag:
  * @tag: An Exiv2 tag
  *
- * The Exiv2 Tag Reference can be found at <ulink url="http://exiv2.org/metadata.html";></ulink>
+ * Check whether @tag is from the IPTC domain of tags.
+ *
+ * The Exiv2 Tag Reference can be found at <http://exiv2.org/metadata.html>
  *
  * Returns: TRUE if the Exiv2 tag is for the IPTC domain.
  */
@@ -445,7 +457,9 @@ gboolean            gexiv2_metadata_is_iptc_tag                             (const gchar* 
tag);
  * gexiv2_metadata_is_xmp_tag:
  * @tag: An Exiv2 tag
  *
- * The Exiv2 Tag Reference can be found at <ulink url="http://exiv2.org/metadata.html";></ulink>
+ * Check whether @tag is from the XMP domain of tags.
+ *
+ * The Exiv2 Tag Reference can be found at <http://exiv2.org/metadata.html>
  *
  * Returns: TRUE if the Exiv2 tag is for the XMP domain.
  */
@@ -456,7 +470,9 @@ gboolean            gexiv2_metadata_is_xmp_tag                              (const gchar* 
tag);
  * @tag: An Exiv2 tag
  * @error: (allow-none): A return location for a #GError or %NULL
  *
- * The Exiv2 Tag Reference can be found at <ulink url="http://exiv2.org/metadata.html";></ulink>
+ * Get Exiv2's label for this tag.
+ *
+ * The Exiv2 Tag Reference can be found at <http://exiv2.org/metadata.html>
  *
  * Returns: (transfer none) (allow-none): The tag's label
  *
@@ -468,7 +484,9 @@ const gchar*        gexiv2_metadata_try_get_tag_label               (const gchar *tag, 
GError **erro
  * gexiv2_metadata_get_tag_label:
  * @tag: An Exiv2 tag
  *
- * The Exiv2 Tag Reference can be found at <ulink url="http://exiv2.org/metadata.html";></ulink>
+ * Get Exiv2's label for this tag.
+ *
+ * The Exiv2 Tag Reference can be found at <http://exiv2.org/metadata.html>
  *
  * Returns: (transfer none) (allow-none): The tag's label
  *
@@ -482,7 +500,9 @@ const gchar*        gexiv2_metadata_get_tag_label           (const gchar *tag);
  * @tag: An Exiv2 tag
  * @error: (allow-none): A return location for a #GError or %NULL
  *
- * The Exiv2 Tag Reference can be found at <ulink url="http://exiv2.org/metadata.html";></ulink>
+ * Get Exiv2's description for a tag.
+ *
+ * The Exiv2 Tag Reference can be found at <http://exiv2.org/metadata.html>
  *
  * Returns: (transfer none) (allow-none): The tag's description
  *
@@ -494,7 +514,9 @@ const gchar*        gexiv2_metadata_try_get_tag_description (const gchar *tag, GError *
  * gexiv2_metadata_get_tag_description:
  * @tag: An Exiv2 tag
  *
- * The Exiv2 Tag Reference can be found at <ulink url="http://exiv2.org/metadata.html";></ulink>
+ * Get Exiv2's description for a tag.
+ *
+ * The Exiv2 Tag Reference can be found at <http://exiv2.org/metadata.html>
  *
  * Returns: (transfer none) (allow-none): The tag's description
  *
@@ -508,10 +530,12 @@ const gchar*      gexiv2_metadata_get_tag_description     (const gchar *tag);
  * @tag: An Exiv2 tag
  * @error: (allow-none): A return location for a #GError or %NULL
  *
+ * Get Exiv2's type name of a tag.
+ *
  * The names of the various Exiv2 tag types can be found at Exiv2::TypeId,
- * <ulink url="http://exiv2.org/doc/namespaceExiv2.html#5153319711f35fe81cbc13f4b852450c";></ulink>
+ * <http://exiv2.org/doc/namespaceExiv2.html#5153319711f35fe81cbc13f4b852450c>
  *
- * The Exiv2 Tag Reference can be found at <ulink url="http://exiv2.org/metadata.html";></ulink>
+ * The Exiv2 Tag Reference can be found at <http://exiv2.org/metadata.html>
  *
  * Returns: (transfer none) (allow-none): The tag's type name.
  *
@@ -523,10 +547,12 @@ const gchar*      gexiv2_metadata_try_get_tag_type        (const gchar *tag, GError 
**error)
  * gexiv2_metadata_get_tag_type:
  * @tag: An Exiv2 tag
  *
+ * Get Exiv2's type name of a tag.
+ *
  * The names of the various Exiv2 tag types can be found at Exiv2::TypeId,
- * <ulink url="http://exiv2.org/doc/namespaceExiv2.html#5153319711f35fe81cbc13f4b852450c";></ulink>
+ * <http://exiv2.org/doc/namespaceExiv2.html#5153319711f35fe81cbc13f4b852450c>
  *
- * The Exiv2 Tag Reference can be found at <ulink url="http://exiv2.org/metadata.html";></ulink>
+ * The Exiv2 Tag Reference can be found at <http://exiv2.org/metadata.html>
  *
  * Returns: (transfer none) (allow-none): The tag's type name.
  *
@@ -541,12 +567,14 @@ const gchar*      gexiv2_metadata_get_tag_type    (const gchar *tag);
  * @tag: An Exiv2 tag
  * @error: (allow-none): A return location for a #GError or %NULL
  *
- * The Exiv2 Tag Reference can be found at <ulink url="https://www.exiv2.org/metadata.html";></ulink>
+ * Check whether a tag supports multiple values.
  *
  * Multiple value tags are Xmp tags of type "XmpAlt", "XmpBag", "XmpSeq" or "LangAlt", or Iptc
  * tags marked as Repeatable (which can be of any Iptc type). There are no multiple value Exif
  * tags.
  *
+ * The Exiv2 Tag Reference can be found at <http://exiv2.org/metadata.html>
+ *
  * Returns: Whether @tag is capable of storing multiple values or not. If @tag is undefined
  * (i.e. not built-in and not added to @self), then @error is set and %FALSE is returned.
  *
@@ -558,7 +586,7 @@ gboolean gexiv2_metadata_try_tag_supports_multiple_values(GExiv2Metadata* self,
  * gexiv2_metadata_get_supports_exif:
  * @self: An instance of #GExiv2Metadata
  *
- * Query @self whether it supports writing EXIF metadata.
+ * Query whether the currently loaded image supports writing of EXIF metadata.
  *
  * Returns: %TRUE if the loaded image type supports writing EXIF metadata.
  */
@@ -568,7 +596,7 @@ gboolean            gexiv2_metadata_get_supports_exif       (GExiv2Metadata *self);
  * gexiv2_metadata_get_supports_iptc:
  * @self: An instance of #GExiv2Metadata
  *
- * Query @self whether it supports writing IPTC metadata.
+ * Query whether the currently loaded image supports writing of IPTC metadata.
  *
  * Returns: %TRUE if the loaded image type supports writing IPTC metadata.
  */
@@ -578,7 +606,7 @@ gboolean            gexiv2_metadata_get_supports_iptc       (GExiv2Metadata *self);
  * gexiv2_metadata_get_supports_xmp:
  * @self: An instance of #GExiv2Metadata
  *
- * Query @self whether it supports writing XMP metadata.
+ * Query whether the currently loaded image supports writing of XMP metadata.
  *
  * Returns: %TRUE if the loaded image type supports writing XMP metadata.
  */
@@ -598,9 +626,9 @@ const gchar*        gexiv2_metadata_get_mime_type           (GExiv2Metadata *self);
  * gexiv2_metadata_get_pixel_width:
  * @self: An instance of #GExiv2Metadata
  *
- * Get the <emphasis>actual</emphasis> unoriented display width in pixels of the loaded
+ * Get the *actual* unoriented display width in pixels of the loaded
  * image. May be different than the width reported by various metadata tags,
- * i.e. "Exif.Photo.PixelXDimension".
+ * i.e. `Exif.Photo.PixelXDimension`.
  *
  * Returns: Pixel width of current image
  */
@@ -610,8 +638,8 @@ gint                        gexiv2_metadata_get_pixel_width         (GExiv2Metadata 
*self);
  * gexiv2_metadata_get_pixel_height:
  * @self: An instance of #GExiv2Metadata
  *
- * Get the <emphasis>actual</emphasis> unoriented display height in pixels of the loaded image.  This may
- * be different than the height reported by various metadata tags, i.e. "Exif.Photo.PixelYDimension".
+ * Get the *actual* unoriented display height in pixels of the loaded image.  This may
+ * be different than the height reported by various metadata tags, i.e. `Exif.Photo.PixelYDimension`.
  *
  * Returns: Pixel height of current image
  */
@@ -623,10 +651,12 @@ gint                      gexiv2_metadata_get_pixel_height        (GExiv2Metadata 
*self);
  * @tag: Exiv2 tag name
  * @error: (allow-none): A return location for a #GError or %NULL
  *
- * The Exiv2 Tag Reference can be found at <ulink url="http://exiv2.org/metadata.html";></ulink>
+ * Get a string representationf a tag.
  *
  * Tags that support multiple values are returned as a single string, with elements separated by ", ".
  *
+ * The Exiv2 Tag Reference can be found at <http://exiv2.org/metadata.html>
+ *
  * Returns: (transfer full) (allow-none): The tag's value as a string
  *
  * Since: 0.12.2
@@ -640,10 +670,12 @@ gchar*                    gexiv2_metadata_try_get_tag_string      (GExiv2Metadata 
*self, const gchar*
  * @value: The value to set or replace the existing value
  * @error: (allow-none): A return location for a #GError or %NULL
  *
+ * Set the value of a tag using a string.
+ *
  * If a tag supports multiple values, then @value is added to any existing values. For single
  * tags, @value replaces the value.
  *
- * The Exiv2 Tag Reference can be found at <ulink url="http://exiv2.org/metadata.html";></ulink>
+ * The Exiv2 Tag Reference can be found at <http://exiv2.org/metadata.html>
  *
  * Returns: TRUE on success
  *
diff --git a/gexiv2/meson.build b/gexiv2/meson.build
index fcea1ff..fb01e2a 100644
--- a/gexiv2/meson.build
+++ b/gexiv2/meson.build
@@ -94,6 +94,7 @@ if introspection_available
                  'gexiv2-startup.h',
                  'gexiv2-metadata.h',
                  'gexiv2-log.h',
+                 'gexiv2-managed-stream.h',
                  version_header,
                  enum_sources.get(1)
                  ],
[Date Prev][Date Next]   [Thread Prev][Thread Next]   [Thread Index] [Date Index] [Author Index]