Documentation: add a number of enums, macros, and structs

7 files changed, 506 insertions, 191 deletions

diff --git a/docs/reference/libgpod-sections.txt b/docs/reference/libgpod-sections.txt
index a930fe7..4c4cd81 100644
--- a/docs/reference/libgpod-sections.txt
+++ b/docs/reference/libgpod-sections.txt
@@ -2,6 +2,7 @@
 <FILE>itunesdb-db</FILE>
 <TITLE>The Itdb_iTunesDB structure</TITLE>
 Itdb_iTunesDB
+ItdbFileError
 ItdbUserDataDestroyFunc
 ItdbUserDataDuplicateFunc
 
@@ -214,8 +215,8 @@ itdb_thumb_to_pixbufs
 <SECTION>
 <FILE>photodb</FILE>
 <TITLE>Photo database</TITLE>
-Itdb_PhotoAlbum
 Itdb_PhotoDB
+Itdb_PhotoAlbum
 itdb_photodb_add_photo
 itdb_photodb_add_photo_from_data
 itdb_photodb_add_photo_from_pixbuf
@@ -280,7 +281,6 @@ db_parse_context_get_m_header
 iPodSong
 DB_TO_CPU_GET
 DB_TO_CPU_GET_DB
-ItdbFileError
 ITDB_FILE_ERROR
 itdb_file_error_quark
 ITDB_DEVICE_ERROR
diff --git a/docs/reference/tmpl/chapterdata.sgml b/docs/reference/tmpl/chapterdata.sgml
index f76f63b..6c83b9b 100644
--- a/docs/reference/tmpl/chapterdata.sgml
+++ b/docs/reference/tmpl/chapterdata.sgml
@@ -2,11 +2,12 @@
 Chapter Data
 
 <!-- ##### SECTION Short_Description ##### -->
-
+Data structure to store chapter data for tracks
 
 <!-- ##### SECTION Long_Description ##### -->
 <para>
-
+Chapters allow for a large file to be divided into sections.  The start and stop
+points in the track are defined here, as well as the title for each chapter.
 </para>
 
 <!-- ##### SECTION See_Also ##### -->
diff --git a/docs/reference/tmpl/itunesdb-db.sgml b/docs/reference/tmpl/itunesdb-db.sgml
index 27d3f52..0d1be9c 100644
--- a/docs/reference/tmpl/itunesdb-db.sgml
+++ b/docs/reference/tmpl/itunesdb-db.sgml
@@ -116,6 +116,17 @@ to the library _duplicate()/_free() functions.
 @userdata_duplicate: 
 @userdata_destroy: 
 
+<!-- ##### ENUM ItdbFileError ##### -->
+<para>
+
+</para>
+
+@ITDB_FILE_ERROR_SEEK: 
+@ITDB_FILE_ERROR_CORRUPT: 
+@ITDB_FILE_ERROR_NOTFOUND: 
+@ITDB_FILE_ERROR_RENAME: 
+@ITDB_FILE_ERROR_ITDB_CORRUPT: 
+
 <!-- ##### USER_FUNCTION ItdbUserDataDestroyFunc ##### -->
 <para>
 
diff --git a/docs/reference/tmpl/libgpod-unused.sgml b/docs/reference/tmpl/libgpod-unused.sgml
index 8df8383..2fae13d 100644
--- a/docs/reference/tmpl/libgpod-unused.sgml
+++ b/docs/reference/tmpl/libgpod-unused.sgml
@@ -118,28 +118,6 @@ iTunesDB
 </para>
 
 
-<!-- ##### ENUM ItdbFileError ##### -->
-<para>
-
-</para>
-
-@ITDB_FILE_ERROR_SEEK: 
-@ITDB_FILE_ERROR_CORRUPT: 
-@ITDB_FILE_ERROR_NOTFOUND: 
-@ITDB_FILE_ERROR_RENAME: 
-@ITDB_FILE_ERROR_ITDB_CORRUPT: 
-
-<!-- ##### ENUM ItdbThumbDataType ##### -->
-<para>
-
-</para>
-
-@ITDB_THUMB_TYPE_INVALID: 
-@ITDB_THUMB_TYPE_FILE: 
-@ITDB_THUMB_TYPE_MEMORY: 
-@ITDB_THUMB_TYPE_PIXBUF: 
-@ITDB_THUMB_TYPE_IPOD: 
-
 <!-- ##### ENUM Itdb_Generation ##### -->
 <para>
 
diff --git a/docs/reference/tmpl/photodb.sgml b/docs/reference/tmpl/photodb.sgml
index 59a7a4d..1d53086 100644
--- a/docs/reference/tmpl/photodb.sgml
+++ b/docs/reference/tmpl/photodb.sgml
@@ -90,11 +90,29 @@ directory of the libgpod source for an example of how to use the interface.
 <!-- ##### SECTION Stability_Level ##### -->
 
 
+<!-- ##### STRUCT Itdb_PhotoDB ##### -->
+<para>
+
+</para>
+
+@photos: 
+@photoalbums: 
+@device: 
+@reserved_int1: 
+@reserved_int2: 
+@reserved1: 
+@reserved2: 
+@usertype: 
+@userdata: 
+@userdata_duplicate: 
+@userdata_destroy: 
+
 <!-- ##### STRUCT Itdb_PhotoAlbum ##### -->
 <para>
 
 </para>
 
+@photodb: 
 @name: 
 @members: 
 @album_type: 
@@ -121,23 +139,6 @@ directory of the libgpod source for an example of how to use the interface.
 @userdata_duplicate: 
 @userdata_destroy: 
 
-<!-- ##### STRUCT Itdb_PhotoDB ##### -->
-<para>
-
-</para>
-
-@photos: 
-@photoalbums: 
-@device: 
-@reserved_int1: 
-@reserved_int2: 
-@reserved1: 
-@reserved2: 
-@usertype: 
-@userdata: 
-@userdata_duplicate: 
-@userdata_destroy: 
-
 <!-- ##### FUNCTION itdb_photodb_add_photo ##### -->
 <para>
 
diff --git a/src/itdb.h b/src/itdb.h
index ea73509..eeb5db7 100644
--- a/src/itdb.h
+++ b/src/itdb.h
@@ -50,7 +50,22 @@ G_BEGIN_DECLS
 #define G_GNUC_INTERNAL
 #endif 
 
+/**
+ * ItdbUserDataDestroyFunc:
+ * @userdata: A #gpointer to user data
+ *
+ * Function called to free userdata
+ */
 typedef void (* ItdbUserDataDestroyFunc) (gpointer userdata);
+
+/**
+ * ItdbUserDataDuplicateFunc:
+ * @userdata: A #gpointer to user data
+ *
+ * Function called to duplicate userdata
+ *
+ * Returns: A #gpointer
+ */
 typedef gpointer (* ItdbUserDataDuplicateFunc) (gpointer userdata);
 
 /* public structures */
@@ -77,6 +92,34 @@ typedef struct _Itdb_Chapterdata Itdb_Chapterdata;
  *
 \* ------------------------------------------------------------ */
 
+/**
+ * Itdb_IpodGeneration:
+ * @ITDB_IPOD_GENERATION_UNKNOWN:   Unknown iPod
+ * @ITDB_IPOD_GENERATION_FIRST:     First Generation iPod
+ * @ITDB_IPOD_GENERATION_SECOND:    Second Generation iPod
+ * @ITDB_IPOD_GENERATION_THIRD:     Third Generation iPod
+ * @ITDB_IPOD_GENERATION_FOURTH:    Fourth Generation iPod
+ * @ITDB_IPOD_GENERATION_PHOTO:     Photo iPod
+ * @ITDB_IPOD_GENERATION_MOBILE:    Mobile iPod
+ * @ITDB_IPOD_GENERATION_MINI_1:    First Generation iPod Mini
+ * @ITDB_IPOD_GENERATION_MINI_2:    Second Generation iPod Mini
+ * @ITDB_IPOD_GENERATION_SHUFFLE_1: First Generation iPod Shuffle
+ * @ITDB_IPOD_GENERATION_SHUFFLE_2: Second Generation iPod Shuffle
+ * @ITDB_IPOD_GENERATION_SHUFFLE_3: Third Generation iPod Shuffle
+ * @ITDB_IPOD_GENERATION_NANO_1:    First Generation iPod Nano
+ * @ITDB_IPOD_GENERATION_NANO_2:    Second Generation iPod Nano
+ * @ITDB_IPOD_GENERATION_NANO_3:    Third Generation iPod Nano
+ * @ITDB_IPOD_GENERATION_VIDEO_1:   First Generation iPod Video (aka 5g)
+ * @ITDB_IPOD_GENERATION_VIDEO_2:   Second Generation iPod Video (aka 5.5g)
+ * @ITDB_IPOD_GENERATION_CLASSIC_1: First Generation iPod Classic
+ * @ITDB_IPOD_GENERATION_TOUCH_1:   First Generation iPod Touch
+ * @ITDB_IPOD_GENERATION_IPHONE_1:  First Generation iPhone
+ *
+ * iPod generation information
+ *
+ * See http://support.apple.com/kb/HT1353 and http://en.wikipedia.org/wiki/IPod
+ * for more details.
+ */
 typedef enum {
     ITDB_IPOD_GENERATION_UNKNOWN,
     ITDB_IPOD_GENERATION_FIRST,
@@ -102,6 +145,45 @@ typedef enum {
     ITDB_IPOD_GENERATION_IPHONE_1,
 } Itdb_IpodGeneration;
 
+/**
+ * Itdb_IpodModel:
+ * @ITDB_IPOD_MODEL_INVALID: Invalid model
+ * @ITDB_IPOD_MODEL_UNKNOWN: Unknown model
+ * @ITDB_IPOD_MODEL_COLOR: Color iPod
+ * @ITDB_IPOD_MODEL_COLOR_U2: Color iPod (U2)
+ * @ITDB_IPOD_MODEL_REGULAR: Regular iPod
+ * @ITDB_IPOD_MODEL_REGULAR_U2: Regular iPod (U2)
+ * @ITDB_IPOD_MODEL_MINI: iPod Mini
+ * @ITDB_IPOD_MODEL_MINI_BLUE: iPod Mini (Blue)
+ * @ITDB_IPOD_MODEL_MINI_PINK: iPod Mini (Pink)
+ * @ITDB_IPOD_MODEL_MINI_GREEN: iPod Mini (Green)
+ * @ITDB_IPOD_MODEL_MINI_GOLD: iPod Mini (Gold)
+ * @ITDB_IPOD_MODEL_SHUFFLE: iPod Shuffle
+ * @ITDB_IPOD_MODEL_NANO_WHITE: iPod Nano (White)
+ * @ITDB_IPOD_MODEL_NANO_BLACK: iPod Nano (Black)
+ * @ITDB_IPOD_MODEL_VIDEO_WHITE: iPod Video (White)
+ * @ITDB_IPOD_MODEL_VIDEO_BLACK: iPod Video (Black)
+ * @ITDB_IPOD_MODEL_MOBILE_1: Mobile iPod
+ * @ITDB_IPOD_MODEL_VIDEO_U2: iPod Video (U2)
+ * @ITDB_IPOD_MODEL_NANO_SILVER: iPod Nano (Silver)
+ * @ITDB_IPOD_MODEL_NANO_BLUE: iPod Nano (Blue)
+ * @ITDB_IPOD_MODEL_NANO_GREEN: iPod Nano (Green)
+ * @ITDB_IPOD_MODEL_NANO_PINK: iPod Nano (Pink)
+ * @ITDB_IPOD_MODEL_NANO_RED: iPod Nano (Red)
+ * @ITDB_IPOD_MODEL_IPHONE_1: iPhone
+ * @ITDB_IPOD_MODEL_SHUFFLE_SILVER: iPod Shuffle (Silver)
+ * @ITDB_IPOD_MODEL_SHUFFLE_PINK: iPod Shuffle (Pink)
+ * @ITDB_IPOD_MODEL_SHUFFLE_BLUE: iPod Shuffle (Blue)
+ * @ITDB_IPOD_MODEL_SHUFFLE_GREEN: iPod Shuffle (Green)
+ * @ITDB_IPOD_MODEL_SHUFFLE_ORANGE: iPod Shuffle (Orange)
+ * @ITDB_IPOD_MODEL_SHUFFLE_PURPLE: iPod Shuffle (Purple)
+ * @ITDB_IPOD_MODEL_SHUFFLE_RED: iPod Shuffle (Red)
+ * @ITDB_IPOD_MODEL_CLASSIC_SILVER: iPod Classic (Silver)
+ * @ITDB_IPOD_MODEL_CLASSIC_BLACK: iPod Classic (Black)
+ * @ITDB_IPOD_MODEL_TOUCH_BLACK: iPod Touch (Black)
+ *
+ * iPod model information
+ */
 typedef enum {
     ITDB_IPOD_MODEL_INVALID,
     ITDB_IPOD_MODEL_UNKNOWN,
@@ -142,19 +224,32 @@ typedef enum {
     ITDB_IPOD_MODEL_TOUCH_BLACK,
 } Itdb_IpodModel;
 
+/**
+ * Itdb_IpodInfo:
+ * @model_number:    The model number.  This is abbreviated.  If the first
+ *                   character is not numeric, it is ommited. e.g.
+ *                   "MA350 -> A350", "M9829 -> 9829"
+ * @capacity:        The iPod's capacity in gigabytes
+ * @ipod_model:      The iPod model
+ * @ipod_generation: The iPod generation
+ * @musicdirs:       The number of music (Fnn) dirs created by iTunes. The
+ *                   exact number seems to be version dependent. Therefore, the
+ *                   numbers here represent a mixture of reported values and
+ *                   common sense.  Note: this number does not necessarily
+ *                   represent the number of dirs present on a particular iPod.
+ *                   It is used when setting up a new iPod from scratch.
+ * @reserved_int1:   Reserved for future use
+ * @reserved_int2:   Reserved for future use
+ * @reserved1:       Reserved for future use
+ * @reserved2:       Reserved for future use
+ *
+ * Structure representing information about an iPod
+ */
 struct _Itdb_IpodInfo {
-    /* model_number is abbreviated: if the first character is not
-       numeric, it is ommited. e.g. "MA350 -> A350", "M9829 -> 9829" */
     const gchar *model_number;
-    const double capacity;  /* in GB */
+    const double capacity;
     const Itdb_IpodModel ipod_model;
     const Itdb_IpodGeneration ipod_generation;
-    /* Number of music (Fnn) dirs created by iTunes. The exact number
-       seems to be version dependent. Therefore, the numbers here
-       represent a mixture of reported values and common sense. Note:
-       this number does not necessarily represent the number of dirs
-       present on a particular iPod. It is used when setting up a new
-       iPod from scratch. */
     const guint musicdirs;
     /* reserved for future use */
     const gint32 reserved_int1;
@@ -177,17 +272,45 @@ struct _Itdb_IpodInfo {
    copy. Further, all enums and #defines below, Itdb_SPLRule, Itdb_SPLRules, and
    Itdb_SPLPref may also be used under a FreeBSD license. */
 
+/**
+ * ITDB_SPL_STRING_MAXLEN:
+ *
+ * Maximum string length for smart playlists
+ */
 #define ITDB_SPL_STRING_MAXLEN 255
+
+/**
+ * ITDB_SPL_DATE_IDENTIFIER:
+ *
+ * Identifier for smart playlist date fields
+ */
 #define ITDB_SPL_DATE_IDENTIFIER (G_GINT64_CONSTANT (0x2dae2dae2dae2daeU))
 
 /* Definitions for smart playlists */
-typedef enum { /* types for match_operator */
-    ITDB_SPLMATCH_AND = 0, /* AND rule - all of the rules must be true in
-			 order for the combined rule to be applied */
-    ITDB_SPLMATCH_OR = 1   /* OR rule */
+
+/**
+ * ItdbSPLMatch:
+ * @ITDB_SPLMATCH_AND: Logical AND - all of the rules must be true in order for
+ *                     the combined rule to be applied
+ * @ITDB_SPLMATCH_OR:  Logical OR - any of the rules may be true
+ *
+ * Types for smart playlist rules match_operator
+ */
+typedef enum {
+    ITDB_SPLMATCH_AND = 0,
+    ITDB_SPLMATCH_OR = 1
 } ItdbSPLMatch;
 
-/* Limit Types.. like limit playlist to 100 minutes or to 100 songs */
+/**
+ * ItdbLimitType:
+ * @ITDB_LIMITTYPE_MINUTES: Limit in minutes
+ * @ITDB_LIMITTYPE_MB:      Limit in megabytes
+ * @ITDB_LIMITTYPE_SONGS:   Limit in number of songs
+ * @ITDB_LIMITTYPE_HOURS:   Limit in hours
+ * @ITDB_LIMITTYPE_GB:      Limit in gigabytes
+ *
+ * The type of unit to use when limiting a playlist
+ */
 typedef enum {
     ITDB_LIMITTYPE_MINUTES = 0x01,
     ITDB_LIMITTYPE_MB      = 0x02,
@@ -196,19 +319,37 @@ typedef enum {
     ITDB_LIMITTYPE_GB      = 0x05
 } ItdbLimitType;
 
-/* Limit Sorts.. Like which songs to pick when using a limit type
-   Special note: the values for ITDB_LIMITSORT_LEAST_RECENTLY_ADDED,
-   ITDB_LIMITSORT_LEAST_OFTEN_PLAYED, ITDB_LIMITSORT_LEAST_RECENTLY_PLAYED, and
-   ITDB_LIMITSORT_LOWEST_RATING are really 0x10, 0x14, 0x15, 0x17, with the
-   'limitsort_opposite' flag set.  This is the same value as the
-   "positive" value (i.e. ITDB_LIMITSORT_LEAST_RECENTLY_ADDED), and is
-   really very terribly awfully weird, so we map the values to iPodDB
-   specific values with the high bit set.
-
-   On writing, we check the high bit and write the limitsort_opposite
-   from that. That way, we don't have to deal with programs using the
-   class needing to set the wrong limit and then make it into the
-   "opposite", which would be frickin' annoying. */
+/**
+ * ItdbLimitSort:
+ * @ITDB_LIMITSORT_RANDOM:                Sort randomly
+ * @ITDB_LIMITSORT_SONG_NAME:             Sort by track name
+ * @ITDB_LIMITSORT_ALBUM:                 Sort by album name
+ * @ITDB_LIMITSORT_ARTIST:                Sort by artist name
+ * @ITDB_LIMITSORT_GENRE:                 Sort by genre
+ * @ITDB_LIMITSORT_MOST_RECENTLY_ADDED:   Sort by most recently added
+ * @ITDB_LIMITSORT_LEAST_RECENTLY_ADDED:  Sort by least recently added
+ * @ITDB_LIMITSORT_MOST_OFTEN_PLAYED:     Sort by most often played
+ * @ITDB_LIMITSORT_LEAST_OFTEN_PLAYED:    Sort by least often played
+ * @ITDB_LIMITSORT_MOST_RECENTLY_PLAYED:  Sort by most recently played
+ * @ITDB_LIMITSORT_LEAST_RECENTLY_PLAYED: Sort by least recently played
+ * @ITDB_LIMITSORT_HIGHEST_RATING:        Sort by highest rating
+ * @ITDB_LIMITSORT_LOWEST_RATING:         Sort by lowest rating
+ *
+ * Which songs to pick when using a limit type
+ *
+ * Note: the values for #ITDB_LIMITSORT_LEAST_RECENTLY_ADDED,
+ * #ITDB_LIMITSORT_LEAST_OFTEN_PLAYED, #ITDB_LIMITSORT_LEAST_RECENTLY_PLAYED,
+ * and #ITDB_LIMITSORT_LOWEST_RATING are really 0x10, 0x14, 0x15, 0x17, with the
+ * 'limitsort_opposite' flag set.  This is the same value as the "positive"
+ * value (i.e. #ITDB_LIMITSORT_LEAST_RECENTLY_ADDED), and is really very
+ * terribly awfully weird, so we map the values to iPodDB specific values with
+ * the high bit set.
+ *
+ * On writing, we check the high bit and write the limitsort_opposite from that.
+ * That way, we don't have to deal with programs using the class needing to set
+ * the wrong limit and then make it into the "opposite", which would be frickin'
+ * annoying.
+ */
 typedef enum {
     ITDB_LIMITSORT_RANDOM = 0x02,
     ITDB_LIMITSORT_SONG_NAME = 0x03,
@@ -302,14 +443,21 @@ typedef enum
 } ItdbSPLActionType;
 
 
-/* These are to pass to AddRule() when you need a unit for the two "in
-   the last" action types Or, in theory, you can use any time
-   range... iTunes might not like it, but the iPod shouldn't care. */
+/**
+ * ItdbSPLActionLast:
+ * @ITDB_SPLACTION_LAST_DAYS_VALUE:   Seconds in 24 hours
+ * @ITDB_SPLACTION_LAST_WEEKS_VALUE:  Seconds in 7 days
+ * @ITDB_SPLACTION_LAST_MONTHS_VALUE: Seconds in 1 month (approximately)
+ *
+ * These are to pass to AddRule() when you need a unit for the two "in the last"
+ * action types.  In theory, you can use any time range.  iTunes might not
+ * like it, but the iPod shouldn't care.
+ */
 typedef enum {
     ITDB_SPLACTION_LAST_DAYS_VALUE = 86400,    /* nr of secs in 24 hours */
     ITDB_SPLACTION_LAST_WEEKS_VALUE = 604800,  /* nr of secs in 7 days   */
     ITDB_SPLACTION_LAST_MONTHS_VALUE = 2628000,/* nr of secs in 30.4167
-					     days ~= 1 month */
+						  days ~= 1 month */
 } ItdbSPLActionLast;
 
 #if 0
@@ -448,10 +596,22 @@ struct _Itdb_SPLRules
  *
 \* ------------------------------------------------------------ */
 
+/**
+ * Itdb_Chapter:
+ * @startpos:      The start position of the chapter in ms. The first chapter
+ *                 begins at 1.
+ * @chaptertitle:  The chapter title in UTF8
+ * @reserved_int1: Reserved for future use
+ * @reserved_int2: Reserved for future use
+ * @reserved1:     Reserved for future use
+ * @reserved2:     Reserved for future use
+ *
+ * Structure representing an iTunesDB Chapter
+ */
 struct _Itdb_Chapter
 {
     guint32 startpos;
-    gchar *chaptertitle;          /* data in UTF8  */
+    gchar *chaptertitle;
     /* reserved for future use */
     gint32 reserved_int1;
     gint32 reserved_int2;
@@ -459,7 +619,19 @@ struct _Itdb_Chapter
     gpointer reserved2;
 };
 
-
+/**
+ * Itdb_Chapterdata:
+ * @chapters:      A list of chapters (#Itdb_Chapter)
+ * @unk024:        Unknown
+ * @unk028:        Unknown
+ * @unk032:        Unknown
+ * @reserved_int1: Reserved for future use
+ * @reserved_int2: Reserved for future use
+ * @reserved1:     Reserved for future use
+ * @reserved2:     Reserved for future use
+ *
+ * Structure representing iTunesDB Chapter data
+ */
 struct _Itdb_Chapterdata
 {
     GList *chapters;
@@ -480,25 +652,50 @@ struct _Itdb_Chapterdata
  *
 \* ------------------------------------------------------------ */
 
-/* one star is how much (track->rating) */
+/**
+ * ITDB_RATING_STEP:
+ *
+ * The multiplier for each star in #track->rating
+ */
 #define ITDB_RATING_STEP 20
 
+/**
+ * Itdb_Artwork:
+ * @thumbnail:          An #Itdb_Thumb
+ * @id:                 Artwork id used by photoalbums.  This starts at 0x40 and
+ *                      is set automatically when the ArtworkDB or PhotoDB is
+ *                      written
+ * @dbid:               The dbid of associated track.  Used internally by
+ *                      libgpod.
+ * @unk028:             Unknown
+ * @rating:             Rating from iPhoto * 20 (PhotoDB only)
+ * @unk036:             Unknown
+ * @creation_date:      Date the image file was created (PhotoDB only)
+ * @digitized_date:     Date the image was taken (EXIF information, PhotoDB
+ *                      only)
+ * @artwork_size:       Size in bytes of the original source image (PhotoDB
+ *                      only -- don't touch in case of ArtworkDB!)
+ * @reserved_int1:      Reserved for future use
+ * @reserved_int2:      Reserved for future use
+ * @reserved1:          Reserved for future use
+ * @reserved2:          Reserved for future use
+ * @usertype:           For use by application
+ * @userdata:           For use by application
+ * @userdata_duplicate: A function to duplicate #userdata
+ * @userdata_destroy:   A function to free #userdata
+ *
+ * Structure representing artwork in an #Itdb_iTunesDB or #Itdb_PhotoDB
+ */
 struct _Itdb_Artwork {
     Itdb_Thumb *thumbnail;
-    guint32 id;            /* Artwork id used by photoalbums, starts at
-			    * 0x40... libgpod will set this on sync. */
-    guint64 dbid;          /* dbid of associated track. used
-			      internally by libgpod */
+    guint32 id;
+    guint64 dbid;
     gint32  unk028;
-    guint32 rating;        /* Rating from iPhoto * 20 (PhotoDB only) */
+    guint32 rating;
     gint32  unk036;
-    time_t  creation_date;  /* Date the image file was created
-			      (creation date of image file (PhotoDB only) */
-    time_t  digitized_date;/* Date the image was taken (EXIF information,
-			      PhotoDB only) */
-    guint32 artwork_size;  /* Size in bytes of the original source
-			      image (PhotoDB only -- don't touch in
-			      case of ArtworkDB!) */
+    time_t  creation_date;
+    time_t  digitized_date;
+    guint32 artwork_size;
     /* reserved for future use */
     gint32 reserved_int1;
     gint32 reserved_int2;
@@ -512,12 +709,27 @@ struct _Itdb_Artwork {
     ItdbUserDataDestroyFunc userdata_destroy;
 };
 
-
+/**
+ * Itdb_PhotoDB:
+ * @photos:             A list of photos in the database (#Itdb_Artwork)
+ * @photoalbums:        A list of albums in the database (#Itdb_PhotoAlbum)
+ * @device:             iPod device info (#Itdb_Device)
+ * @reserved_int1:      Reserved for future use
+ * @reserved_int2:      Reserved for future use
+ * @reserved1:          Reserved for future use
+ * @reserved2:          Reserved for future use
+ * @usertype:           For use by application
+ * @userdata:           For use by application
+ * @userdata_duplicate: A function to duplicate #userdata
+ * @userdata_destroy:   A function to free #userdata
+ *
+ * Structure representing an iTunes Photo database
+ */
 struct _Itdb_PhotoDB
 {
-    GList *photos;      /* (Itdb_Artwork *)     */
-    GList *photoalbums; /* (Itdb_PhotoAlbum *)  */
-    Itdb_Device *device;/* iPod device info     */
+    GList *photos;
+    GList *photoalbums;
+    Itdb_Device *device;
     /* reserved for future use */
     gint32 reserved_int1;
     gint32 reserved_int2;
@@ -531,12 +743,31 @@ struct _Itdb_PhotoDB
     ItdbUserDataDestroyFunc userdata_destroy;
 };
 
+/**
+ * Itdb_iTunesDB:
+ * @tracks:             A list of tracks in the database (#Itdb_Track)
+ * @playlists:          A list of playlists in the database (#Itdb_Playlist)
+ * @filename:           The filename of the iTunesDB
+ * @device:             iPod device info (#Itdb_Device)
+ * @version:            The version number of the iTunesDB
+ * @id:                 A 64 bit id value for the iTunesDB
+ * @reserved_int1:      Reserved for future use
+ * @reserved_int2:      Reserved for future use
+ * @reserved1:          Reserved for future use
+ * @reserved2:          Reserved for future use
+ * @usertype:           For use by application
+ * @userdata:           For use by application
+ * @userdata_duplicate: A function to duplicate #userdata
+ * @userdata_destroy:   A function to free #userdata
+ *
+ * Structure representing an iTunes database
+ */
 struct _Itdb_iTunesDB
 {
     GList *tracks;
     GList *playlists;
-    gchar *filename;    /* filename of iTunesDB */
-    Itdb_Device *device;/* iPod device info     */
+    gchar *filename;
+    Itdb_Device *device;
     guint32 version;
     guint64 id;
     /* reserved for future use */
@@ -552,32 +783,60 @@ struct _Itdb_iTunesDB
     ItdbUserDataDestroyFunc userdata_destroy;
 };
 
+/**
+ * Itdb_PhotoAlbum:
+ * @photodb:              A pointer to the #Itdb_PhotoDB (for convenience)
+ * @name:                 The name of photoalbum in UTF8
+ * @members:              A list of photos in album (#Itdb_Artwork)
+ * @album_type:           The album type.  0x01 for master (Photo Library),
+ *                        0x02 for a normal album.  (4 and 5 have also been
+ *                        seen.)
+ * @playmusic:            Play music during slideshow
+ * @repeat:               Repeat the slideshow
+ * @random:               Show slides in random order
+ * @show_titles:          Show slide captions
+ * @transition_direction: Transition direction.  0=none, 1=left-to-right,
+ *                        2=right-to-left, 3=top-to-bottom, 4=bottom-to-top
+ * @slide_duration:       Slide duration in seconds
+ * @transition_duration:  Transition duration, in milliseconds
+ * @song_id:              The @dbid2 of a track to play during slideshow
+ * @unk024:               Unknown, seems to be always 0
+ * @unk028:               Unknown, seems to be always 0
+ * @unk044:               Unknown, seems to always be 0
+ * @unk048:               Unknown, seems to always be 0
+ * @album_id:             The id of the album.  This is set automatically when
+ *                        the PhotoDB is written.
+ * @prev_album_id:        The id of the previous playlist.  This is set
+ *                        automatically when the PhotoDB is written.
+ * @reserved_int1:        Reserved for future use
+ * @reserved_int2:        Reserved for future use
+ * @reserved1:            Reserved for future use
+ * @reserved2:            Reserved for future use
+ * @usertype:             For use by application
+ * @userdata:             For use by application
+ * @userdata_duplicate:   A function to duplicate #userdata
+ * @userdata_destroy:     A function to free #userdata
+ *
+ * Structure representing an iTunes Photo Album
+ */
 struct _Itdb_PhotoAlbum
 {
-    Itdb_PhotoDB *photodb;       /* database to which this album belongs  */
-    gchar *name;                 /* name of photoalbum in UTF8            */
-    GList *members;              /* photos in album (Itdb_Artwork *)      */
-    guint8 album_type;           /* 0x01 for master (Photo Library),
-				    0x02 otherwise (sometimes 4 and 5)    */
-    guint8 playmusic;            /* play music during slideshow (from
-				    iPhoto setting)                       */
-    guint8 repeat;               /* repeat the slideshow (from iPhoto
-				    setting)                              */
-    guint8 random;               /* show the slides in random order
-			            (from iPhoto setting)                 */
-    guint8 show_titles;          /* show slide captions (from iPhoto
-				    setting)                              */
-    guint8 transition_direction; /* 0=none, 1=left-to-right,
-				    2=right-to-left, 3=top-to-bottom,
-				    4=bottom-to-top (from iPhoto setting) */
-    gint32 slide_duration;       /* in seconds (from iPhoto setting)      */
-    gint32 transition_duration;  /* in milliseconds (from iPhoto setting) */
-    gint64 song_id;              /* dbid2 of track in iTunesDB to play
-				    during slideshow (from iPhoto setting)*/
-    gint32 unk024;               /* unknown, seems to be always 0         */
-    gint16 unk028;               /* unknown, seems to be always 0         */
-    gint32 unk044;               /* unknown, seems to always be 0         */
-    gint32 unk048;               /* unknown, seems to always be 0         */
+    Itdb_PhotoDB *photodb;
+    gchar *name;
+    GList *members;
+    guint8 album_type;
+    guint8 playmusic;
+    guint8 repeat;
+    guint8 random;
+    guint8 show_titles;
+    guint8 transition_direction;
+    gint32 slide_duration;
+    gint32 transition_duration;
+    gint64 song_id;
+    gint32 unk024;
+    gint16 unk028;
+    gint32 unk044;
+    gint32 unk048;
     /* set automatically at time of writing the PhotoDB */
     gint32  album_id;
     gint32  prev_album_id;
@@ -594,25 +853,61 @@ struct _Itdb_PhotoAlbum
     ItdbUserDataDestroyFunc userdata_destroy;
 };
 
+/**
+ * Itdb_Playlist:
+ * @itdb:               A pointer to the #Itdb_iTunesDB (for convenience)
+ * @name:               The name of the playlist in UTF8
+ * @type:               The playlist type (normal or master)
+ * @flag1:              Unknown, usually set to 0
+ * @flag2:              Unknown, always set to 0
+ * @flag3:              Unknown, always set to 0
+ * @num:                The number of tracks in the playlist
+ * @members:            A list of tracks in the playlist (#Itdb_Track)
+ * @is_spl:             True if the playlist is a smart playlist, otherwise
+ *                      false
+ * @timestamp:          When the playlist was created
+ * @id:                 The playlist ID
+ * @sortorder:          The playlist sort order (#ItdbPlaylistSortOrder)
+ * @podcastflag:        This is set to 0 on normal playlists and to 1 for the
+ *                      Podcast playlist. If set to 1, the playlist will not be
+ *                      shown under 'Playlists' on the iPod, but as 'Podcasts'
+ *                      under the Music menu. The actual title of the Playlist
+ *                      does not matter. If more than one playlist is set to 1,
+ *                      they don't show up at all.
+ * @splpref:            Smart playlist preferences (#Itdb_SPLPref)
+ * @splrules:           Smart playlist rules (#Itdb_SPLRules)
+ * @reserved100:        Reserved for MHOD100 implementation
+ * @reserved101:        Reserved for MHOD100 implementation
+ * @reserved_int1:      Reserved for future use
+ * @reserved_int2:      Reserved for future use
+ * @reserved1:          Reserved for future use
+ * @reserved2:          Reserved for future use
+ * @usertype:           For use by application
+ * @userdata:           For use by application
+ * @userdata_duplicate: A function to duplicate #userdata
+ * @userdata_destroy:   A function to free #userdata
+ *
+ * Structure representing an iTunes Playlist
+ */
 struct _Itdb_Playlist
 {
-    Itdb_iTunesDB *itdb;  /* pointer to iTunesDB (for convenience) */
-    gchar *name;          /* name of playlist in UTF8              */
-    guint8 type;          /* ITDB_PL_TYPE_NORM/_MPL                */
-    guint8 flag1;         /* unknown, usually set to 0             */
-    guint8 flag2;         /* unknown, always set to 0              */
-    guint8 flag3;         /* unknown, always set to 0              */
-    gint  num;            /* number of tracks in playlist          */
-    GList *members;       /* tracks in playlist (Track *)          */
-    gboolean is_spl;      /* smart playlist?                       */
-    time_t timestamp;     /* timestamp of playlist creation        */
-    guint64 id;           /* playlist ID                           */
-    guint32 sortorder;    /* How to sort playlist -- see below     */
-    guint32 podcastflag;  /* ITDB_PL_FLAG_NORM/_PODCAST            */
-    Itdb_SPLPref splpref;      /* smart playlist prefs                  */
-    Itdb_SPLRules splrules;    /* rules for smart playlists             */
-    gpointer reserved100; /* reserved for MHOD100 implementation   */
-    gpointer reserved101; /* reserved for MHOD100 implementation   */
+    Itdb_iTunesDB *itdb;
+    gchar *name;
+    guint8 type;
+    guint8 flag1;
+    guint8 flag2;
+    guint8 flag3;
+    gint  num;
+    GList *members;
+    gboolean is_spl;
+    time_t timestamp;
+    guint64 id;
+    guint32 sortorder;
+    guint32 podcastflag;
+    Itdb_SPLPref splpref;
+    Itdb_SPLRules splrules;
+    gpointer reserved100;
+    gpointer reserved101;
     /* reserved for future use */
     gint32 reserved_int1;
     gint32 reserved_int2;
@@ -627,39 +922,37 @@ struct _Itdb_Playlist
 };
 
 
-/*
-Playlist Sort Order
-
-1 - playlist order (manual sort order)
-2 - ???
-3 - songtitle
-4 - album
-5 - artist
-6 - bitrate
-7 - genre
-8 - kind
-9 - date modified
-10 - track nr
-11 - size
-12 - time
-13 - year
-14 - sample rate
-15 - comment
-16 - date added
-17 - equalizer
-18 - composer
-19 - ???
-20 - play count
-21 - last played
-22 - disc nr
-23 - my rating
-24 - release date (I guess, it's the value for the "Podcasts" list)
-25 - BPM
-26 - grouping
-27 - category
-28 - description
-*/
-
+/**
+ * ItdbPlaylistSortOrder:
+ * @ITDB_PSO_MANUAL:        Sort by playlist order (manual sort)
+ * @ITDB_PSO_TITLE:         Sort by track title
+ * @ITDB_PSO_ALBUM:         Sort by album
+ * @ITDB_PSO_ARTIST:        Sort by artist
+ * @ITDB_PSO_BIRATE:        Sort by bitrate
+ * @ITDB_PSO_GENRE:         Sort by genre
+ * @ITDB_PSO_FILETYPE:      Sort by filetype
+ * @ITDB_PSO_TIME_MODIFIED: Sort by date modified
+ * @ITDB_PSO_TRACK_NR:      Sort by track number
+ * @ITDB_PSO_SIZE:          Sort by track size
+ * @ITDB_PSO_TIME:          Sort by track time
+ * @ITDB_PSO_YEAR:          Sort by year
+ * @ITDB_PSO_SAMPLERATE:    Sort by samplerate
+ * @ITDB_PSO_COMMENT:       Sort by comments
+ * @ITDB_PSO_TIME_ADDED:    Sort by date added
+ * @ITDB_PSO_EQUALIZER:     Sort by equilizer
+ * @ITDB_PSO_COMPOSER:      Sort by composer
+ * @ITDB_PSO_PLAYCOUNT:     Sort by playcount
+ * @ITDB_PSO_TIME_PLAYED:   Sort by date last played
+ * @ITDB_PSO_CD_NR:         Sort by disc number
+ * @ITDB_PSO_RATING:        Sort by rating
+ * @ITDB_PSO_RELEASE_DATE:  Sort by release date
+ * @ITDB_PSO_BPM:           Sort by beats per minute
+ * @ITDB_PSO_GROUPING:      Sort by grouping
+ * @ITDB_PSO_CATEGORY:      Sort by category
+ * @ITDB_PSO_DESCRIPTION:   Sort by description
+ *
+ * Playlist Sort Order
+ */
 typedef enum
 {
     ITDB_PSO_MANUAL = 1,
@@ -693,7 +986,21 @@ typedef enum
 } ItdbPlaylistSortOrder;
 
 
-/* Mediatype definitions */
+/**
+ * Itdb_Mediatype:
+ * @ITDB_MEDIATYPE_AUDIO:      Audio files
+ * @ITDB_MEDIATYPE_MOVIE:      Movies
+ * @ITDB_MEDIATYPE_PODCAST:    Podcasts
+ * @ITDB_MEDIATYPE_AUDIOBOOK:  Audio books
+ * @ITDB_MEDIATYPE_MUSICVIDEO: Music videos
+ * @ITDB_MEDIATYPE_TVSHOW:     TV Shows
+ *
+ * Mediatype definitions
+ *
+ * The mediatype is used to determine what menu a track appears under.  For
+ * example, setting the mediatype to #ITDB_MEDIATYPE_PODCAST makes the track
+ * appear on the Podcast menu.
+ */
 typedef enum
 {
     ITDB_MEDIATYPE_AUDIO      = 0x0001,
@@ -977,13 +1284,24 @@ struct _Itdb_Track
  * Error codes
  *
 \* ------------------------------------------------------------ */
+
+/**
+ * ItdbFileError:
+ * @ITDB_FILE_ERROR_SEEK:         file corrupt: illegal seek occured
+ * @ITDB_FILE_ERROR_CORRUPT:      file corrupt
+ * @ITDB_FILE_ERROR_NOTFOUND:     file not found
+ * @ITDB_FILE_ERROR_RENAME:       file could not be renamed
+ * @ITDB_FILE_ERROR_ITDB_CORRUPT: iTunesDB in memory corrupt
+ *
+ * Error codes for iTunesDB file
+ */
 typedef enum
 {
-    ITDB_FILE_ERROR_SEEK,        /* file corrupt: illegal seek occured */
-    ITDB_FILE_ERROR_CORRUPT,     /* file corrupt                       */
-    ITDB_FILE_ERROR_NOTFOUND,    /* file not found                     */
-    ITDB_FILE_ERROR_RENAME,      /* file could not be renamed          */
-    ITDB_FILE_ERROR_ITDB_CORRUPT /* iTunesDB in memory corrupt         */
+    ITDB_FILE_ERROR_SEEK,
+    ITDB_FILE_ERROR_CORRUPT,
+    ITDB_FILE_ERROR_NOTFOUND,
+    ITDB_FILE_ERROR_RENAME,
+    ITDB_FILE_ERROR_ITDB_CORRUPT
 } ItdbFileError;
 
 
diff --git a/src/itdb_device.h b/src/itdb_device.h
index 1888a27..0d1839f 100644
--- a/src/itdb_device.h
+++ b/src/itdb_device.h
@@ -74,24 +74,30 @@ enum _ItdbThumbFormat
     THUMB_FORMAT_EXPERIMENTAL_BE,
 };
 
+/**
+ * Itdb_Device:
+ * @mountpoint: The mountpoint of the iPod
+ * @musicdirs: The number of /iPod_Control/Music/F.. dirs
+ * @byte_order: G_LITTLE_ENDIAN "regular" endianness G_BIG_ENDIAN "reversed"
+ * endianness (e.g. mobile phone iTunesDBs)
+ * @sysinfo: A hash with key/value pairs of all entries in Device/SysInfo
+ * @sysinfo_extended: The parsed content of SysInfoExtended, which can be NULL
+ * @sysinfo_changed: True if the sysinfo hash been changed by the user, false
+ * otherwise.  (see #itdb_set_sysinfo)
+ * @timezone_shift: The difference in seconds between the current timezone and
+ * UTC
+ *
+ * Structure representing an iPod device
+ */
 struct _Itdb_Device
 {
-    gchar *mountpoint;    /* mountpoint of the iPod */
-    gint   musicdirs;     /* number of /iPod_Control/Music/F.. dirs */
-    guint  byte_order;    /* G_LITTLE_ENDIAN "regular" endianness 
-			   * G_BIG_ENDIAN "reversed" endianness (e.g. mobile
-			   * phone iTunesDBs)
-			   */
-    GHashTable *sysinfo;  /* hash with value/key pairs of all entries
-			   * in Device/SysInfo */
-    SysInfoIpodProperties *sysinfo_extended; /* parsed content of 
-                                              * SysInfoExtended, can be NULL */
-    gboolean sysinfo_changed; /* Has the sysinfo hash been changed by
-				 the user (itdb_set_sysinfo) */
-    gint timezone_shift;  /* difference in seconds between the current
-                           * timezone and UTC
-                           */
-
+    gchar *mountpoint;
+    gint   musicdirs;
+    guint  byte_order;
+    GHashTable *sysinfo;
+    SysInfoIpodProperties *sysinfo_extended;
+    gboolean sysinfo_changed;
+    gint timezone_shift;
 };
 
 struct _Itdb_ArtworkFormat {