Documented some return values in the case of errors.

Also, added docs for a few functions that were missing them.
Fixes issue #18.
[skip ci]

diff --git a/libexif/exif-byte-order.h b/libexif/exif-byte-order.h
index 10ded49..f48fb5e 100644 (file)
--- a/libexif/exif-byte-order.h
+++ b/libexif/exif-byte-order.h
@@ -37,7 +37,7 @@ typedef enum {
 
 /*! Return a short, localized, textual name for the given byte order.
  * \param[in] order byte order
- * \return localized textual name of the byte order
+ * \return localized textual name of the byte order, or NULL if unknown
  */
 const char *exif_byte_order_get_name (ExifByteOrder order);
 

diff --git a/libexif/exif-content.h b/libexif/exif-content.h
index d912ccf..a86acee 100644 (file)
--- a/libexif/exif-content.h
+++ b/libexif/exif-content.h
@@ -49,10 +49,46 @@ struct _ExifContent
 };
 
 /* Lifecycle */
+
+/*! Reserve memory for and initialize a new #ExifContent.
+ *
+ * \return new allocated #ExifContent, or NULL on error
+ *
+ * \see exif_content_new_mem, exif_content_unref
+ */
 ExifContent *exif_content_new     (void);
+
+/*! Reserve memory for and initialize new #ExifContent using the specified
+ * memory allocator.
+ *
+ * \return new allocated #ExifContent, or NULL on error
+ *
+ * \see exif_content_new, exif_content_unref
+ */
 ExifContent *exif_content_new_mem (ExifMem *);
+
+/*! Increase reference counter for #ExifContent.
+ *
+ * \param[in] content #ExifContent
+ *
+ * \see exif_content_unref
+ */
 void         exif_content_ref     (ExifContent *content);
+
+/*! Decrease reference counter for #ExifContent.
+ * When the reference count drops to zero, free the content.
+ *
+ * \param[in] content #ExifContent
+ */
 void         exif_content_unref   (ExifContent *content);
+
+/*! Actually free the #ExifContent.
+ *
+ * \deprecated Should not be called directly. Use #exif_content_ref and
+ *             #exif_content_unref instead.
+ *
+ * \param[in] content #ExifContent
+ */
 void         exif_content_free    (ExifContent *content);
 
 /*! Add an EXIF tag to an IFD.

diff --git a/libexif/exif-data.h b/libexif/exif-data.h
index eeee782..7d87d1d 100644 (file)
--- a/libexif/exif-data.h
+++ b/libexif/exif-data.h
@@ -185,14 +185,16 @@ typedef enum {
 /*! Return a short textual description of the given #ExifDataOption.
  *
  * \param[in] o option
- * \return localized textual description of the option
+ * \return localized textual description of the option,
+ *   or NULL if unknown
  */
 const char *exif_data_option_get_name        (ExifDataOption o);
 
 /*! Return a verbose textual description of the given #ExifDataOption.
  *
  * \param[in] o option
- * \return verbose localized textual description of the option
+ * \return verbose localized textual description of the option,
+ *   or NULL if unknown
  */
 const char *exif_data_option_get_description (ExifDataOption o);
 

diff --git a/libexif/exif-entry.h b/libexif/exif-entry.h
index 1dcdc73..def5347 100644 (file)
--- a/libexif/exif-entry.h
+++ b/libexif/exif-entry.h
@@ -156,7 +156,8 @@ void        exif_entry_fix        (ExifEntry *entry);
  *          supported.
  *
  * \param[in] entry EXIF entry
- * \param[out] val buffer in which to store value
+ * \param[out] val buffer in which to store value; if entry is valid and
+ *   maxlen > 0 then this string will be NUL-terminated
  * \param[in] maxlen length of the buffer val
  * \return val pointer
  */

diff --git a/libexif/exif-format.h b/libexif/exif-format.h
index b7a79a4..9bbc320 100644 (file)
--- a/libexif/exif-format.h
+++ b/libexif/exif-format.h
@@ -47,7 +47,7 @@ typedef enum {
 /*! Return a textual representation of the given EXIF data type.
  *
  * \param[in] format EXIF data format
- * \return localized textual name
+ * \return localized textual name, or NULL if unknown
  */
 const char   *exif_format_get_name (ExifFormat format);
 

diff --git a/libexif/exif-ifd.h b/libexif/exif-ifd.h
index 26c4053..0d29491 100644 (file)
--- a/libexif/exif-ifd.h
+++ b/libexif/exif-ifd.h
@@ -36,7 +36,7 @@ typedef enum {
  * characters.
  *
  * \param[in] ifd IFD
- * \return textual name of the IFD
+ * \return textual name of the IFD, or NULL if unknown
  */
 const char *exif_ifd_get_name (ExifIfd ifd);
 

diff --git a/libexif/exif-log.h b/libexif/exif-log.h
index 9e71ad6..1b3bf4b 100644 (file)
--- a/libexif/exif-log.h
+++ b/libexif/exif-log.h
@@ -61,14 +61,14 @@ typedef enum {
 /*! Return a textual description of the given class of error log.
  *
  * \param[in] code logging message class
- * \return textual description of the log class
+ * \return textual description of the log class, or NULL if unknown
  */
 const char *exif_log_code_get_title   (ExifLogCode code);
 
 /*! Return a verbose description of the given class of error log.
  *
  * \param[in] code logging message class
- * \return verbose description of the log class
+ * \return verbose description of the log class, or NULL if unknown
  */
 const char *exif_log_code_get_message (ExifLogCode code);
 

diff --git a/libexif/exif-mem.h b/libexif/exif-mem.h
index fd8f2fa..93bf705 100644 (file)
--- a/libexif/exif-mem.h
+++ b/libexif/exif-mem.h
@@ -61,6 +61,7 @@ typedef struct _ExifMem ExifMem;
  * \param[in] a the allocator function
  * \param[in] r the reallocator function
  * \param[in] f the free function
+ * \return allocated #ExifMem, or NULL on error
  */
 ExifMem *exif_mem_new   (ExifMemAllocFunc a, ExifMemReallocFunc r,
                         ExifMemFreeFunc f);

diff --git a/libexif/exif-mnote-data.h b/libexif/exif-mnote-data.h
index 7e55a95..048ddf2 100644 (file)
--- a/libexif/exif-mnote-data.h
+++ b/libexif/exif-mnote-data.h
@@ -78,7 +78,7 @@ unsigned int exif_mnote_data_get_id          (ExifMnoteData *d, unsigned int n);
  *
  * \param[in] d MakerNote data
  * \param[in] n index of the entry within the MakerNote data
- * \return textual name of the tag
+ * \return textual name of the tag or NULL on error
  */
 const char  *exif_mnote_data_get_name        (ExifMnoteData *d, unsigned int n);
 
@@ -87,7 +87,7 @@ const char  *exif_mnote_data_get_name        (ExifMnoteData *d, unsigned int n);
  *
  * \param[in] d MakerNote data
  * \param[in] n index of the entry within the MakerNote data
- * \return textual name of the tag
+ * \return textual name of the tag or NULL on error
  */
 const char  *exif_mnote_data_get_title       (ExifMnoteData *d, unsigned int n);
 
@@ -95,7 +95,7 @@ const char  *exif_mnote_data_get_title       (ExifMnoteData *d, unsigned int n);
  *
  * \param[in] d MakerNote data
  * \param[in] n index of the entry within the MakerNote data
- * \return textual description of the tag
+ * \return textual description of the tag or NULL on error
  */
 const char  *exif_mnote_data_get_description (ExifMnoteData *d, unsigned int n);