Improved Doxygen documentation.

diff --git a/libexif/exif-data.h b/libexif/exif-data.h
index a1a6472f65f0e86025f754df40979eca495e3d82..feae15ba4eb5c6af3d29f79cadb486f1fcb42f2a 100644 (file)
--- a/libexif/exif-data.h
+++ b/libexif/exif-data.h
@@ -42,6 +42,7 @@ typedef struct _ExifDataPrivate ExifDataPrivate;
 #include <libexif/exif-mnote-data.h>
 #include <libexif/exif-mem.h>
 
+/*! \internal */
 struct _ExifData
 {
        ExifContent *ifd[EXIF_IFD_COUNT];

diff --git a/libexif/exif-entry.h b/libexif/exif-entry.h
index b9ec76c36901d71f891a3403098a4a07363a59ae..34d1e9379ba498131407d669cbf1691bdf1e179a 100644 (file)
--- a/libexif/exif-entry.h
+++ b/libexif/exif-entry.h
@@ -27,7 +27,11 @@
 extern "C" {
 #endif /* __cplusplus */
 
-/*! Data found in one EXIF tag */
+/*! Data found in one EXIF tag.
+ * The #exif_entry_get_value function can provide access to the
+ * formatted contents, or the struct members can be used directly to
+ * access the raw contents.
+ */
 typedef struct _ExifEntry        ExifEntry;
 typedef struct _ExifEntryPrivate ExifEntryPrivate;
 
@@ -35,33 +39,61 @@ typedef struct _ExifEntryPrivate ExifEntryPrivate;
 #include <libexif/exif-format.h>
 #include <libexif/exif-mem.h>
 
-/*! */
+/*! Data found in one EXIF tag */
 struct _ExifEntry {
+       /*! EXIF tag for this entry */
         ExifTag tag;
+       
+       /*! Type of data in this entry */
         ExifFormat format;
+
+       /*! Number of elements in the array, if this is an array entry.
+        * Contains 1 for non-array data types. */
         unsigned long components;
 
+       /*! Pointer to the raw EXIF data for this entry. It is allocated
+        * by #exif_entry_initialize and is NULL beforehand. Data contained
+        * here may be manipulated using the functions in exif-utils.h */
         unsigned char *data;
+
+       /*! Number of bytes in the buffer at \c data. This must be no less
+        * than exif_format_get_size(format)*components */
         unsigned int size;
 
-       /* Content containing this entry */
+       /*! #ExifContent containing this entry. 
+        * \see #exif_entry_get_ifd */
        ExifContent *parent;
 
+       /*! Internal data to be used by libexif itself */
        ExifEntryPrivate *priv;
 };
 
 /* Lifecycle */
 
-/*! Reserve memory for and initialize new #ExifEntry.
- * \return new allocated #ExifEntry
+/*! Reserve memory for and initialize a new #ExifEntry.
+ * No memory is allocated for the \c data element of the returned #ExifEntry.
+ *
+ * \return new allocated #ExifEntry, or NULL on error
+ *
+ * \see exif_entry_new_mem, exif_entry_unref
  */
 ExifEntry  *exif_entry_new     (void);
 
+/*! Reserve memory for and initialize new #ExifEntry using the specified
+ * memory allocator.
+ * No memory is allocated for the \c data element of the returned #ExifEntry.
+ *
+ * \return new allocated #ExifEntry, or NULL on error
+ *
+ * \see exif_entry_new, exif_entry_unref
+ */
 ExifEntry  *exif_entry_new_mem (ExifMem *);
 
 /*! Increase reference counter for #ExifEntry.
  *
  * \param[in] entry #ExifEntry
+ *
+ * \see exif_entry_unref
  */
 void        exif_entry_ref     (ExifEntry *entry);
 
@@ -84,19 +116,30 @@ void        exif_entry_free  (ExifEntry *entry);
 /*! Initialize an empty #ExifEntry with default data in the correct format
  * for the given tag. If the entry is already initialized, this function
  * does nothing.
+ * This call allocates memory for the \c data element of the given #ExifEntry.
+ * That memory is freed at the same time as the #ExifEntry.
  *
  * \param[out] e entry to initialize
  * \param[in] tag tag number to initialize as
  */
 void        exif_entry_initialize (ExifEntry *e, ExifTag tag);
 
-/*! When necessary and possible, fix the type or format of the given
- * EXIF entry when it is of the wrong type or in an invalid format.
+/*! Fix the type or format of the given EXIF entry to bring it into spec.
+ * If the data for this EXIF tag is in of the wrong type or is in an invalid
+ * format according to the EXIF specification, then it is converted to make it
+ * valid. This may involve, for example, converting an EXIF_FORMAT_LONG into a
+ * EXIF_FORMAT_SHORT. If the tag is unknown, its value is untouched.
+ *
+ * \note Unfortunately, some conversions are to a type with a more resticted
+ * range, which could have the side effect that the converted data becomes
+ * invalid. This is unlikely as the range of each tag in the standard is
+ * designed to encompass all likely data.
  *
  * \param[in,out] entry EXIF entry
  */
 void        exif_entry_fix        (ExifEntry *entry);
 
+
 /* For your convenience */
 
 /*! Return a textual representation of the value of the EXIF entry.
@@ -121,7 +164,7 @@ const char *exif_entry_get_value (ExifEntry *entry, char *val,
  */
 void        exif_entry_dump      (ExifEntry *entry, unsigned int indent);
 
-/*! Returns the IFD number of the given #ExifEntry
+/*! Return the IFD number of the given #ExifEntry
  *
  * \param[in] e an #ExifEntry*
  * \return #ExifIfd, or #EXIF_IFD_COUNT on error

diff --git a/libexif/exif-loader.c b/libexif/exif-loader.c
index 21e85fb6d7ebf386239fc234bae2b2698107e024..4340369c03bbaf9c1bc33dad505e44e7ba5c6fe4 100644 (file)
--- a/libexif/exif-loader.c
+++ b/libexif/exif-loader.c
@@ -63,11 +63,12 @@ typedef enum {
        EL_DATA_FORMAT_FUJI_RAW
 } ExifLoaderDataFormat;
 
+/*! \internal */
 struct _ExifLoader {
        ExifLoaderState state;
        ExifLoaderDataFormat data_format;
 
-       /* Small buffer used for detection of format */
+       /*! Small buffer used for detection of format */
        unsigned char b[12];
        unsigned char b_len;
 
@@ -81,6 +82,7 @@ struct _ExifLoader {
        ExifMem *mem;
 };
 
+/*! Magic number for EXIF header */
 static const unsigned char ExifHeader[] = {0x45, 0x78, 0x69, 0x66, 0x00, 0x00};
 
 static void *

diff --git a/libexif/exif-loader.h b/libexif/exif-loader.h
index 8e085377461c2e80e24a33ae26e617d3c1f54c48..88851b7653ca4aa5e82866d13612a8d89b253801 100644 (file)
--- a/libexif/exif-loader.h
+++ b/libexif/exif-loader.h
@@ -34,20 +34,20 @@ extern "C" {
 /*! Data used by the loader interface */
 typedef struct _ExifLoader ExifLoader;
 
-/*! Allocate a new #ExifLoader
+/*! Allocate a new #ExifLoader.
  *
  *  \return allocated ExifLoader
  */
 ExifLoader *exif_loader_new     (void);
 
-/*! Allocate a new #ExifLoader using an #ExifMem
+/*! Allocate a new #ExifLoader using the specified memory allocator.
  *
  *  \param[in] mem the ExifMem
  *  \return allocated ExifLoader
  */
 ExifLoader *exif_loader_new_mem (ExifMem *mem);
 
-/*! Increase the refcount of the #ExifLoader
+/*! Increase the refcount of the #ExifLoader.
  *
  *  \param[in] loader the ExifLoader to increase the refcount of.
  */
@@ -61,6 +61,7 @@ void        exif_loader_ref     (ExifLoader *loader);
 void        exif_loader_unref   (ExifLoader *loader);
 
 /*! Load a file into the given #ExifLoader from the filesystem.
+ * The relevant data is copied in raw form into the #ExifLoader.
  *
  * \param[in] loader loader to write to
  * \param[in] fname path to the file to read
@@ -68,6 +69,7 @@ void        exif_loader_unref   (ExifLoader *loader);
 void        exif_loader_write_file (ExifLoader *loader, const char *fname);
 
 /*! Load a buffer into the #ExifLoader from a memory buffer.
+ * The relevant data is copied in raw form into the #ExifLoader.
  *
  * \param[in] loader loader to write to
  * \param[in] buf buffer to read from
@@ -77,13 +79,16 @@ void        exif_loader_write_file (ExifLoader *loader, const char *fname);
  */
 unsigned char exif_loader_write (ExifLoader *loader, unsigned char *buf, unsigned int sz);
 
-/*! Reset the ExifLoader to its newly-initialized state
+/*! Free any data previously loaded and reset the #ExifLoader to its
+ * newly-initialized state.
  *
  * \param[in] loader the loader
  */
 void          exif_loader_reset (ExifLoader *loader);
 
-/*! Create an ExifData from an ExifLoader
+/*! Create an #ExifData from the data in the loader. The loader must
+ * already contain data from a previous call to #exif_loader_write_file
+ * or #exif_loader_write.
  *
  * \param[in] loader the loader
  * \return allocated ExifData

diff --git a/libexif/exif-log.h b/libexif/exif-log.h
index e2ad473b79026479b5d4eccda025d98c685c2655..90bacea32d2a0ef242adb7260a1e11ff260d0bb4 100644 (file)
--- a/libexif/exif-log.h
+++ b/libexif/exif-log.h
@@ -78,8 +78,9 @@ typedef void (* ExifLogFunc) (ExifLog *log, ExifLogCode, const char *domain,
                              const char *format, va_list args, void *data);
 
 /*! Register log callback function.
+ * Calls to the log callback function are purely for diagnostic purposes.
  *
- * \param[in] log #ExifLog
+ * \param[in] log logging state variable
  * \param[in] func callback function to set
  * \param[in] data data to pass into callback function
  */

diff --git a/libexif/exif-tag.h b/libexif/exif-tag.h
index e5be37aaa9a4be9b43293f2fd32e2f0e5040c58f..6cc3ce70e57015491c71997441a14fa25f71e5c6 100644 (file)
--- a/libexif/exif-tag.h
+++ b/libexif/exif-tag.h
@@ -210,24 +210,25 @@ ExifTag          exif_tag_from_name                (const char *name);
  *
  * \param[in] tag EXIF tag
  * \param[in] ifd IFD
- * \return textual name of the tag
+ * \return textual name of the tag, or NULL if the tag is unknown
  */
 const char      *exif_tag_get_name_in_ifd          (ExifTag tag, ExifIfd ifd);
 
 /*! Return a textual title of the given tag when found in the given IFD.
+ * The title is a short, localized description of the tag.
  *
  * \param[in] tag EXIF tag
  * \param[in] ifd IFD
- * \return textual title of the tag
+ * \return textual title of the tag, or NULL if the tag is unknown
  */
 const char      *exif_tag_get_title_in_ifd         (ExifTag tag, ExifIfd ifd);
 
 /*! Return a verbose textual description of the given tag when found in the
- * given IFD.
+ * given IFD. The description is a verbose, localized description of the tag.
  *
  * \param[in] tag EXIF tag
  * \param[in] ifd IFD
- * \return textual description of the tag
+ * \return textual description of the tag, or NULL if the tag is unknown
  */
 const char      *exif_tag_get_description_in_ifd   (ExifTag tag, ExifIfd ifd);
 

diff --git a/libexif/olympus/mnote-olympus-tag.h b/libexif/olympus/mnote-olympus-tag.h
index 0b6fab33d7681f8b103494840bd1a105fd2a19bd..0fc485b3a0c3b3eb046065b3beaaa5aef9d5ef93 100644 (file)
--- a/libexif/olympus/mnote-olympus-tag.h
+++ b/libexif/olympus/mnote-olympus-tag.h
@@ -187,8 +187,31 @@ typedef enum _MnoteOlympusTag MnoteOlympusTag;
 #define MNOTE_OLYMPUS_TAG_UNKNOWN_2    MNOTE_OLYMPUS_TAG_FOCALPLANEDIAGONAL
 #define MNOTE_OLYMPUS_TAG_UNKNOWN_3    MNOTE_OLYMPUS_TAG_LENSDISTORTION
 
+/*! Return a textual name of the given tag within the Olympus-style MakerNote.
+ * The name is a short, unique, non-localized text string containing only
+ * US-ASCII alphanumeric characters.
+ *
+ * \param[in] tag Olympus-style MakerNote tag
+ * \return textual name of the tag, or NULL if the tag is unknown
+ */
 const char *mnote_olympus_tag_get_name        (MnoteOlympusTag tag);
+
+/*! Return a textual title of the given tag within the Olympus-style MakerNote.
+ * The title is a short, localized description of the tag.
+ *
+ * \param[in] tag Olympus-style MakerNote tag
+ * \return textual title of the tag, or NULL if the tag is unknown
+ */
 const char *mnote_olympus_tag_get_title       (MnoteOlympusTag tag);
+
+/*! Return a verbose textual description of the given tag within the
+ * Olympus-style MakerNote.
+ * The description is a verbose, localized description of the tag.
+ *
+ * \param[in] tag EXIF tag
+ * \param[in] ifd IFD
+ * \return textual description of the tag, or NULL if the tag is unknown
+ */
 const char *mnote_olympus_tag_get_description (MnoteOlympusTag tag);
 
 #ifdef __cplusplus