[gexiv2] doc: Update several documentations

From: Jens Georg <jensgeorg src gnome org>
To: commits-list gnome org
Cc:
Subject: [gexiv2] doc: Update several documentations
Date: Mon, 20 Mar 2017 11:18:27 +0000 (UTC)
commit 67726b2da344a0903c4fa4b5d79e0d055ed326a9
Author: Jens Georg <mail jensge org>
Date:   Mon Mar 20 12:08:57 2017 +0100

    doc: Update several documentations
    
    Signed-off-by: Jens Georg <mail jensge org>

 gexiv2/gexiv2-log.cpp           |    5 --
 gexiv2/gexiv2-log.h             |   14 +++-
 gexiv2/gexiv2-metadata-exif.cpp |   35 +++++++++
 gexiv2/gexiv2-metadata.h        |  151 +++++++++++++++++++++++++++++++++++----
 gexiv2/gexiv2-startup.h         |   10 ++-
 5 files changed, 192 insertions(+), 23 deletions(-)
---
diff --git a/gexiv2/gexiv2-log.cpp b/gexiv2/gexiv2-log.cpp
index 2f47f15..4db257a 100644
--- a/gexiv2/gexiv2-log.cpp
+++ b/gexiv2/gexiv2-log.cpp
@@ -9,11 +9,6 @@
 
 #include "gexiv2-log-private.h"
 
-/**
- * SECTION:gexiv2-log
- * @short: FOo
- */
-
 G_BEGIN_DECLS
 
 static GExiv2LogHandler installed_handler = NULL;
diff --git a/gexiv2/gexiv2-log.h b/gexiv2/gexiv2-log.h
index c5467a6..3a1a3b3 100644
--- a/gexiv2/gexiv2-log.h
+++ b/gexiv2/gexiv2-log.h
@@ -12,6 +12,16 @@
 
 #include <glib.h>
 
+/**
+ * SECTION:gexiv2-log
+ * @title: Logging functionality
+ * @short_description: Utility functions related to GExiv2's and Exiv2's logging.
+ *
+ * The functions in this modules can be used do configure the log level of
+ * GExiv2 and Exiv2 in terms of what to log (see gexiv2_log_set_level()) and
+ * how. Either a custom log handler can be used or GLib's logging mechanisms.
+ */
+
 G_BEGIN_DECLS
 
 /**
@@ -86,11 +96,11 @@ void                                gexiv2_log_set_handler(GExiv2LogHandler handler);
  * gexiv2_log_use_glib_logging:
  *
  * When called, gexiv2 will install it's own #GExiv2LogHandler which redirects all Exiv2 and gexiv2
- * log messages to GLib's logging calls (g_debug, g_message, g_warning, and g_critical for the
+ * log messages to GLib's logging calls (g_debug(), g_message(), g_warning(), and g_critical() for the
  * respective #GExiv2LogLevel value).  #GEXIV2_LOG_LEVEL_MUTE logs are dropped.
  *
  * One advantage to using this is that GLib's logging control and handlers can be used rather than
- * gexiv2's ad hoc scheme.  It also means an application can use GLib logging and have all its
+ * GExiv2's ad hoc scheme.  It also means an application can use GLib logging and have all its
  * messages routed through the same calls.
  */
 void                           gexiv2_log_use_glib_logging(void);
diff --git a/gexiv2/gexiv2-metadata-exif.cpp b/gexiv2/gexiv2-metadata-exif.cpp
index d7e20ad..c87a460 100644
--- a/gexiv2/gexiv2-metadata-exif.cpp
+++ b/gexiv2/gexiv2-metadata-exif.cpp
@@ -197,6 +197,17 @@ gboolean gexiv2_metadata_set_exif_tag_long (GExiv2Metadata *self, const gchar* t
     return FALSE;
 }
 
+/**
+ * gexiv2_metadata_get_exif_tag_rational:
+ * @self: An instance of #GExiv2Metadata
+ * @tag: Name of the tag to fetch
+ * @nom: (out): Return value for the nominator of the rational value of @tag
+ * @den: (out): Return location for the denominator of the rational value of @tag
+ *
+ * Get an Exif tag that is stored as a fraction
+ *
+ * Returns: %TRUE on success, %FALSE otherwise.
+ */
 gboolean gexiv2_metadata_get_exif_tag_rational (GExiv2Metadata *self, const gchar* tag, gint* nom,
     gint* den) {
     g_return_val_if_fail(GEXIV2_IS_METADATA (self), FALSE);
@@ -226,6 +237,17 @@ gboolean gexiv2_metadata_get_exif_tag_rational (GExiv2Metadata *self, const gcha
     return FALSE;
 }
 
+/**
+ * gexiv2_metadata_set_exif_tag_rational:
+ * @self: An instance of #GExiv2Metadata
+ * @tag: Name of the tag to fetch
+ * @nom: The nominator of the rational value of @tag
+ * @den: The denominator of the rational value of @tag
+ *
+ * Set an Exif tag that is stored as a fraction
+ *
+ * Returns: %TRUE on success, %FALSE otherwise.
+ */
 gboolean gexiv2_metadata_set_exif_tag_rational (GExiv2Metadata *self, const gchar* tag, gint nom, 
     gint den) {
     g_return_val_if_fail(GEXIV2_IS_METADATA (self), FALSE);
@@ -246,6 +268,19 @@ gboolean gexiv2_metadata_set_exif_tag_rational (GExiv2Metadata *self, const gcha
     return FALSE;
 }
 
+/**
+ * gexiv2_metadata_get_exif_tag_rational_as_double:
+ * @self: An instance of #GExiv2Metadata
+ * @tag: Name of the tag to fetch
+ * @def: Default value that is returned in error case
+ *
+ * A convenience wrapper around gexiv2_metadata_get_exif_tag_rational() that
+ * will convert the fraction into a floating point number.
+ *
+ * Returns: 0.0 if the nominator of the fraction is 0.0, @def if the fraction
+ * would be a division by zero or the tag could not be read, the fraction as a
+ * floating point value otherwise.
+ */
 gdouble gexiv2_metadata_get_exif_tag_rational_as_double (GExiv2Metadata *self, const gchar* tag, gdouble 
def) {
     gint nom, den;
     if (!gexiv2_metadata_get_exif_tag_rational(self, tag, &nom, &den))
diff --git a/gexiv2/gexiv2-metadata.h b/gexiv2/gexiv2-metadata.h
index ddfcf36..fd6b64b 100644
--- a/gexiv2/gexiv2-metadata.h
+++ b/gexiv2/gexiv2-metadata.h
@@ -17,6 +17,50 @@
 #include <gexiv2/gexiv2-preview-properties.h>
 #include <gexiv2/gexiv2-preview-image.h>
 
+/**
+ * SECTION: gexiv2-metadata
+ * @short_description: Class to handle the various image metadata standards
+ *
+ * #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 specifig tags of a specific format, be it EXIF, IPTC
+ * or XMP
+ */
+
+/**
+ * SECTION: gexiv2-preview-image
+ * @short_description: Class describing preview images (or thumbnails) that
+ * are part of the metadata.
+ * @see_also: #GExiv2Metadata #GExiv2PreviewProperties
+ *
+ * #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.
+ * <informalexample><programlisting>
+ * GExiv2PreviewProperties **properties, **it;
+ * properts = it = gexiv2_metadata_get_preview_properties(metadata);
+ *
+ * while (*it) {
+ *   preview_image = gexiv2_metadata_get_preview_image(metadata, *it);
+ *   it++;
+ * }
+ * </programlisting></informalexample>
+ */
+
+/**
+ * SECTION: gexiv2-preview-properties
+ * @short_description: Class describing properties of a preview image
+ * @see_also: #GExiv2Metadata #GExiv2PreviewProperties
+ *
+ * Metadata can contain multiple preview images. #GExiv2PreviewProperties are
+ * used to describe the available image without the need of fetching the whole
+ * image from the metadta.
+ */
+
 G_BEGIN_DECLS
 
 #define GEXIV2_TYPE_METADATA \
@@ -347,7 +391,9 @@ const gchar*        gexiv2_metadata_get_tag_type    (const gchar *tag);
  * gexiv2_metadata_get_supports_exif:
  * @self: An instance of #GExiv2Metadata
  *
- * Returns: TRUE if the loaded image type supports writing EXIF metadata.
+ * Query @self whehter it suports writing EXIF metadata.
+ *
+ * Returns: %TRUE if the loaded image type supports writing EXIF metadata.
  */
 gboolean               gexiv2_metadata_get_supports_exif       (GExiv2Metadata *self);
 
@@ -355,7 +401,9 @@ gboolean            gexiv2_metadata_get_supports_exif       (GExiv2Metadata *self);
  * gexiv2_metadata_get_supports_iptc:
  * @self: An instance of #GExiv2Metadata
  *
- * Returns: TRUE if the loaded image type supports writing IPTC metadata.
+ * Query @self whether it supports writing IPTC metadata.
+ *
+ * Returns: %TRUE if the loaded image type supports writing IPTC metadata.
  */
 gboolean               gexiv2_metadata_get_supports_iptc       (GExiv2Metadata *self);
 
@@ -363,14 +411,19 @@ gboolean          gexiv2_metadata_get_supports_iptc       (GExiv2Metadata *self);
  * gexiv2_metadata_get_supports_xmp:
  * @self: An instance of #GExiv2Metadata
  *
- * Returns: TRUE if the loaded image type supports writing XMP metadata.
+ * Query @self whether it supports writing XMP metadata.
+ *
+ * Returns: %TRUE if the loaded image type supports writing XMP metadata.
  */
 gboolean               gexiv2_metadata_get_supports_xmp        (GExiv2Metadata *self);
 
 /**
- * gexiv2_get_mime_type:
+ * gexiv2_metadata_get_mime_type:
+ * @self: An instance of #GExiv2Metadata
  *
- * Returns: (transfer none): The MIME type of the loaded image, NULL if not loaded or unknown.
+ * Query mime type of currently loaded image.
+ *
+ * Returns: (transfer none): The MIME type of the loaded image, %NULL if not loaded or unknown.
  */
 const gchar*   gexiv2_metadata_get_mime_type           (GExiv2Metadata *self);
 
@@ -378,8 +431,11 @@ const gchar*       gexiv2_metadata_get_mime_type           (GExiv2Metadata *self);
  * gexiv2_metadata_get_pixel_width:
  * @self: An instance of #GExiv2Metadata
  *
- * Returns: The <em>actual</em> unoriented display width in pixels of the loaded image.  This may be
- * different than the width reported by various metadata tags, i.e. "Exif.Photo.PixelXDimension".
+ * Get the <emphasis>actual</emphasis> 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".
+ *
+ * Returns: Pixel width of current image
  */
 gint                   gexiv2_metadata_get_pixel_width         (GExiv2Metadata *self);
 
@@ -387,8 +443,10 @@ gint                       gexiv2_metadata_get_pixel_width         (GExiv2Metadata 
*self);
  * gexiv2_metadata_get_pixel_height:
  * @self: An instance of #GExiv2Metadata
  *
- * Returns: The <em>actual</em> unoriented display height in pixels of the loaded image.  This may
+ * 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".
+ *
+ * Returns: Pixel height of current image
  */
 gint                   gexiv2_metadata_get_pixel_height        (GExiv2Metadata *self);
 
@@ -524,6 +582,8 @@ void                        gexiv2_metadata_clear_exif                      
(GExiv2Metadata *self);
  * gexiv2_metadata_get_exif_tags:
  * @self: An instance of #GExiv2Metadata
  *
+ * Query @self for a list of available EXIF tags
+ *
  * Returns: (transfer full) (array zero-terminated=1): A list of the available EXIF tags in the
  * loaded image
  */
@@ -536,6 +596,9 @@ gchar**                     gexiv2_metadata_get_exif_tags           (GExiv2Metadata 
*self);
  * @nom: (out): The numerator
  * @den: (out): The denominator
  *
+ * Fetch EXIF @tag represented by a fraction. @nom will contian the numerator,
+ * @den the denominator of the fraction on successful return.
+ *
  * Returns: (skip): Boolean success value
  */
 gboolean               gexiv2_metadata_get_exif_tag_rational (GExiv2Metadata *self, const gchar* tag, gint* 
nom, gint* den);
@@ -547,6 +610,9 @@ gboolean            gexiv2_metadata_get_exif_tag_rational (GExiv2Metadata *self, const gch
  * @nom: Rational numerator
  * @den: Rational denominator
  *
+ * Set EXIF @tag represented by a fraction, with @nom being the numerator,
+ * @den the denominator of the fraction.
+ *
  * Returns: (skip): Boolean success value
  */
 gboolean               gexiv2_metadata_set_exif_tag_rational (GExiv2Metadata *self, const gchar* tag, gint 
nom, gint den);
@@ -557,6 +623,8 @@ gboolean            gexiv2_metadata_set_exif_tag_rational (GExiv2Metadata *self, const gch
  * @buffer: (out) (array length=size) (transfer full): Where to store the thumbnail data
  * @size: (skip): Size of the thumbnail's buffer
  *
+ * Get the thumbnail stored in the EXIF data of @self
+ *
  * Returns: (skip): Boolean success value
  */
 gboolean               gexiv2_metadata_get_exif_thumbnail (GExiv2Metadata *self, guint8** buffer, gint* 
size);
@@ -616,7 +684,9 @@ void                        gexiv2_metadata_clear_xmp                       
(GExiv2Metadata *self);
  * @xmp_format_flags: One of #GExiv2XmpFormatFlags
  * @padding: The padding (FIXME: Add documentation)
  *
- * Returns: (transfer full) (allow-none): Encode the XMP packet and return as a NUL-terminated string.
+ * Encode the XMP packet as a %NULL-terminated string.
+ *
+ * Returns: (transfer full) (allow-none): Encode the XMP packet and return as a %NULL-terminated string.
  */
 gchar*         gexiv2_metadata_generate_xmp_packet     (GExiv2Metadata *self, GExiv2XmpFormatFlags 
xmp_format_flags, guint32 padding);
 
@@ -680,6 +750,8 @@ void                        gexiv2_metadata_clear_iptc                      
(GExiv2Metadata *self);
  * gexiv2_metadata_get_iptc_tags:
  * @self: An instance of #GExiv2Metadata
  *
+ * Query @self for a list of available IPTC tags
+ *
  * Returns: (transfer full) (array zero-terminated=1): A list of the available IPTC tags
  */
 gchar**                        gexiv2_metadata_get_iptc_tags           (GExiv2Metadata *self);
@@ -692,7 +764,10 @@ gchar**                    gexiv2_metadata_get_iptc_tags           (GExiv2Metadata 
*self);
  * gexiv2_metadata_get_orientation:
  * @self: An instance of #GExiv2Metadata
  *
- * Returns: The EXIF Orientation field.
+ * The EXIF Orientation field
+ *
+ * Returns: A #GExiv2Orientation value representing the EXIF orientation
+ * value.
  */
 GExiv2Orientation gexiv2_metadata_get_orientation      (GExiv2Metadata *self);
 
@@ -705,9 +780,46 @@ GExiv2Orientation gexiv2_metadata_get_orientation  (GExiv2Metadata *self);
  */
 void                   gexiv2_metadata_set_orientation         (GExiv2Metadata *self, GExiv2Orientation 
orientation);
 
+/**
+ * gexiv2_metadata_get_metadata_pixel_width:
+ * @self: An instance of #GExiv2Metadata
+ *
+ * Composite accessor to query the pixel with stored in the metadata. This
+ * might differ from the width of image that is available through
+ * gexiv2_metadata_get_pixel_width()
+ *
+ * Returns: Width of images in pixels as stored in the metadata
+ */
 gint gexiv2_metadata_get_metadata_pixel_width (GExiv2Metadata *self);
+
+/**
+ * gexiv2_metadata_get_metadata_pixel_height:
+ * @self: An instance of #GExiv2Metadata
+ *
+ * Composite accessor to query the pixel with stored in the metadata. This
+ * might differ from the height of image that is available through
+ * gexiv2_metadata_get_pixel_height()
+ *
+ * Returns: Height of images in pixels as stored in the metadata
+ */
 gint gexiv2_metadata_get_metadata_pixel_height (GExiv2Metadata *self);
+
+/**
+ * gexiv2_metadata_set_metadata_pixel_width:
+ * @self: An instance of #GExiv2Metadata
+ * @width: The width of the image as it should be put into the metadta.
+ *
+ * Composite setter to update the image's metadata with @width
+ */
 void gexiv2_metadata_set_metadata_pixel_width (GExiv2Metadata *self, gint width);
+
+/**
+ * gexiv2_metadata_set_metadata_pixel_height:
+ * @self: An instance of #GExiv2Metadata
+ * @height: The width of the image as it should be put into the metadta.
+ *
+ * Update the image's metadata with @height
+ */
 void gexiv2_metadata_set_metadata_pixel_height (GExiv2Metadata *self, gint height);
 
 /**
@@ -717,7 +829,7 @@ void gexiv2_metadata_set_metadata_pixel_height (GExiv2Metadata *self, gint heigh
  * A composite accessor that uses the first available metadata field from a list of well-known
  * locations to find the photo's comment (or description).  
  *
- * MWG guidelines refer to these as <em>Description</em>: a textual description of a resource's content.
+ * MWG guidelines refer to these as <emphasis>Description</emphasis>: a textual description of a resource's 
content.
  * 
  * These fields are:
  *
@@ -728,10 +840,10 @@ void gexiv2_metadata_set_metadata_pixel_height (GExiv2Metadata *self, gint heigh
  * - Xmp.dc.description           (MWG Guidelines)
  * - Xmp.acdsee.notes             (Commonly requested, read only)
  *
- * <note><para>that in the EXIF specification Exif.Image.ImageDescription is
+ * <note>Note that in the EXIF specification Exif.Image.ImageDescription is
  * described  as "the title of the image".  Also, it does not support
  * two-byte character codes for encoding.  However, it's still used here for legacy reasons.
- * </para></note>
+ * </note>
  *
  * For fine-grained control, it's recommened to use Exiv2 tags directly rather than this method,
  * which is more useful for quick or casual use.
@@ -765,7 +877,7 @@ void                        gexiv2_metadata_clear_comment           (GExiv2Metadata 
*self);
  * @nom: (out): The numerator
  * @den: (out): The denominator
  *
- * Returns the exposure time in seconds (shutter speed, <em>not</em> date-time of exposure) as a
+ * Returns the exposure time in seconds (shutter speed, <emphasis>not</emphasis> date-time of exposure) as a
  * rational.  See <ulink url="https://en.wikipedia.org/wiki/Shutter_speed";></ulink> for more information.
  *
  * Returns: (skip): Boolean success value
@@ -811,6 +923,8 @@ gint                        gexiv2_metadata_get_iso_speed           (GExiv2Metadata 
*self);
  * @self: An instance of #GExiv2Metadata
  * @longitude: (out): Variable to store the longitude value
  *
+ * Query the longitude stored in the GPS tags of @self
+ *
  * Returns: (skip): Boolean success value
  */
 gboolean               gexiv2_metadata_get_gps_longitude                       (GExiv2Metadata *self, 
gdouble *longitude);
@@ -820,6 +934,8 @@ gboolean            gexiv2_metadata_get_gps_longitude                       
(GExiv2Metadata *self, gdouble *lo
  * @self: An instance of #GExiv2Metadata
  * @latitude: (out): Variable to store the latitude value
  *
+ * Query the latitude stored in the GPS tags of @self
+ *
  * Returns: (skip): Boolean success value
  */
 gboolean               gexiv2_metadata_get_gps_latitude                        (GExiv2Metadata *self, 
gdouble *latitude);
@@ -829,6 +945,9 @@ gboolean            gexiv2_metadata_get_gps_latitude                        
(GExiv2Metadata *self, gdouble *lat
  * @self: An instance of #GExiv2Metadata
  * @altitude: (out): Variable to store the altitude value
  *
+ * Convenience functon to query the altitude stored in the GPS tags of the
+ * image
+ *
  * Returns: (skip): Boolean success value
  */
 gboolean               gexiv2_metadata_get_gps_altitude                        (GExiv2Metadata *self, 
gdouble *altitude);
@@ -840,6 +959,8 @@ gboolean            gexiv2_metadata_get_gps_altitude                        
(GExiv2Metadata *self, gdouble *alt
  * @latitude: (out): Storage for latitude value
  * @altitude: (out): Storage for altitude value
  *
+ * Convenience functon to query all available GPS information at once.
+ *
  * Returns: (skip): Boolean success value.
  */
 gboolean               gexiv2_metadata_get_gps_info                            (GExiv2Metadata *self, 
gdouble *longitude, gdouble *latitude, gdouble *altitude);
@@ -851,6 +972,8 @@ gboolean            gexiv2_metadata_get_gps_info                            
(GExiv2Metadata *self, gdouble *longit
  * @latitude: Latitude value to set or replace current value
  * @altitude: Altitude value to set or replace current value
  *
+ * Convenience functon to query all available GPS information at once.
+ *
  * Returns: (skip): Boolean success value.
  */
 gboolean               gexiv2_metadata_set_gps_info                            (GExiv2Metadata *self, 
gdouble longitude, gdouble latitude, gdouble altitude);
diff --git a/gexiv2/gexiv2-startup.h b/gexiv2/gexiv2-startup.h
index 0caba72..c5fd76f 100644
--- a/gexiv2/gexiv2-startup.h
+++ b/gexiv2/gexiv2-startup.h
@@ -12,6 +12,12 @@
 
 #include <glib-object.h>
 
+/**
+ * SECTION:gexiv2-startup
+ * @title: Library initialisation
+ * @short_description:Functions that need to be called to set up the GExiv2 library.
+ */
+
 G_BEGIN_DECLS
 
 /**
@@ -19,9 +25,9 @@ G_BEGIN_DECLS
  *
  * gexiv2 requires initialization before its methods are used.  In particular, this call must be
  * made in a thread-safe fashion.  Best practice is to call from the application's main thread and
- * not to use any gexiv2 code until it has returned.
+ * not to use any Gexiv2 code until it has returned.
  *
- * Returns: TRUE if initialized.  If FALSE, gexiv2 should not be used (unable to initialize
+ * Returns: %TRUE if initialized.  If %FALSE, GExiv2 should not be used (unable to initialize
  * properly).
  */
 gboolean gexiv2_initialize(void);
[Date Prev][Date Next] [Thread Prev][Thread Next] [Thread Index] [Date Index] [Author Index]