Update API documentation

Add new functions and missing enums, macros, and structs to the proper
places in the documentation, remove old/unused functions, and clean up
various minor issues.

git-svn-id: https://gtkpod.svn.sf.net/svnroot/gtkpod/libgpod/trunk@2159 f01d2545-417e-4e96-918e-98f8d0dbbcb6

14 files changed, 1983 insertions, 1078 deletions

diff --git a/src/itdb.h b/src/itdb.h
index 9a5cd96..925c552 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,38 @@ 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_NANO_4:    Fourth 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_CLASSIC_2: Second 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.
+ *
+ * Since: 0.4.0
+ */
 typedef enum {
     ITDB_IPOD_GENERATION_UNKNOWN,
     ITDB_IPOD_GENERATION_FIRST,
@@ -102,6 +149,50 @@ 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_NANO_YELLOW:    iPod Nano (Yellow)
+ * @ITDB_IPOD_MODEL_NANO_PURPLE:    iPod Nano (Purple)
+ * @ITDB_IPOD_MODEL_NANO_ORANGE:    iPod Nano (Orange)
+ * @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
+ *
+ * Since: 0.4.0
+ */
 typedef enum {
     ITDB_IPOD_MODEL_INVALID,
     ITDB_IPOD_MODEL_UNKNOWN,
@@ -142,19 +233,34 @@ 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
+ *
+ * Since: 0.4.0
+ */
 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 +283,51 @@ 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
+ *
+ * Since: 0.5.0
+ */
 #define ITDB_SPL_STRING_MAXLEN 255
+
+/**
+ * ITDB_SPL_DATE_IDENTIFIER:
+ *
+ * Identifier for smart playlist date fields
+ *
+ * Since: 0.5.0
+ */
 #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
+ *
+ * Since: 0.5.0
+ */
 typedef enum {
     ITDB_LIMITTYPE_MINUTES = 0x01,
     ITDB_LIMITTYPE_MB      = 0x02,
@@ -196,19 +336,39 @@ 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.
+ *
+ * Since: 0.5.0
+ */
 typedef enum {
     ITDB_LIMITSORT_RANDOM = 0x02,
     ITDB_LIMITSORT_SONG_NAME = 0x03,
@@ -225,28 +385,57 @@ typedef enum {
     ITDB_LIMITSORT_LOWEST_RATING = 0x80000017,        /* See note above */
 } ItdbLimitSort;
 
-/* Smartlist Actions - Used in the rules.
-Note by Otto (Samuel Wood):
- really this is a bitmapped field...
- high byte
- bit 0 = "string" values if set, "int" values if not set
- bit 1 = "not", or to negate the check.
- lower 2 bytes
- bit 0 = simple "IS" query
- bit 1 = contains
- bit 2 = begins with
- bit 3 = ends with
- bit 4 = greater than
- bit 5 = unknown, but probably greater than or equal to
- bit 6 = less than
- bit 7 = unknown, but probably less than or equal to
- bit 8 = a range selection
- bit 9 = "in the last"
+/**
+ * ItdbSPLAction:
+ * @ITDB_SPLACTION_IS_INT:              is integer ("Is Set" in iTunes)
+ * @ITDB_SPLACTION_IS_GREATER_THAN:     is greater than ("Is after" in iTunes)
+ * @ITDB_SPLACTION_IS_LESS_THAN:        is less than ("Is Before" in iTunes)
+ * @ITDB_SPLACTION_IS_IN_THE_RANGE:     is in the range
+ * @ITDB_SPLACTION_IS_IN_THE_LAST:      is in the last
+ * @ITDB_SPLACTION_BINARY_AND:          binary AND
+ * @ITDB_SPLACTION_IS_STRING:           is a string
+ * @ITDB_SPLACTION_CONTAINS:            contains
+ * @ITDB_SPLACTION_STARTS_WITH:         starts with
+ * @ITDB_SPLACTION_ENDS_WITH:           ends with
+ * @ITDB_SPLACTION_IS_NOT_INT:          is not an integer ("Is Not Set" in iTunes)
+ * @ITDB_SPLACTION_IS_NOT_GREATER_THAN: is not greater than (not in iTunes)
+ * @ITDB_SPLACTION_IS_NOT_LESS_THAN:    is not less than (not in iTunes)
+ * @ITDB_SPLACTION_IS_NOT_IN_THE_RANGE: is not in the range (not in iTunes)
+ * @ITDB_SPLACTION_IS_NOT_IN_THE_LAST:  is not in the last
+ * @ITDB_SPLACTION_IS_NOT:              is not
+ * @ITDB_SPLACTION_DOES_NOT_CONTAIN:    does not contain
+ * @ITDB_SPLACTION_DOES_NOT_START_WITH: does not start with (not in iTunes)
+ * @ITDB_SPLACTION_DOES_NOT_END_WITH:   does not end with (not in iTunes)
+ *
+ * Smartlist Actions used in smart playlist rules.
+ *
+ * Note by Otto (Samuel Wood):
+ * <informalexample>
+ *  <programlisting>
+ *  really this is a bitmapped field...
+ *  high byte
+ *  bit 0 = "string" values if set, "int" values if not set
+ *  bit 1 = "not", or to negate the check.
+ *  lower 2 bytes
+ *  bit 0 = simple "IS" query
+ *  bit 1 = contains
+ *  bit 2 = begins with
+ *  bit 3 = ends with
+ *  bit 4 = greater than
+ *  bit 5 = unknown, but probably greater than or equal to
+ *  bit 6 = less than
+ *  bit 7 = unknown, but probably less than or equal to
+ *  bit 8 = a range selection
+ *  bit 9 = "in the last"
+ *  </programlisting>
+ * </informalexample>
+ *
+ * Since: 0.5.0
 */
 typedef enum {
-    ITDB_SPLACTION_IS_INT = 0x00000001,          /* "Is Set" in iTunes */
-    ITDB_SPLACTION_IS_GREATER_THAN = 0x00000010, /* "Is After" in iTunes */
-    ITDB_SPLACTION_IS_LESS_THAN = 0x00000040,    /* "Is Before" in iTunes */
+    ITDB_SPLACTION_IS_INT = 0x00000001,
+    ITDB_SPLACTION_IS_GREATER_THAN = 0x00000010,
+    ITDB_SPLACTION_IS_LESS_THAN = 0x00000040,
     ITDB_SPLACTION_IS_IN_THE_RANGE = 0x00000100,
     ITDB_SPLACTION_IS_IN_THE_LAST = 0x00000200,
     ITDB_SPLACTION_BINARY_AND = 0x00000400,
@@ -256,25 +445,32 @@ typedef enum {
     ITDB_SPLACTION_STARTS_WITH = 0x01000004,
     ITDB_SPLACTION_ENDS_WITH = 0x01000008,
 
-    ITDB_SPLACTION_IS_NOT_INT = 0x02000001,     /* "Is Not Set" in iTunes */
-
-    /* Note: Not available in iTunes 4.5 (untested on iPod) */
+    ITDB_SPLACTION_IS_NOT_INT = 0x02000001,
     ITDB_SPLACTION_IS_NOT_GREATER_THAN = 0x02000010,
-    /* Note: Not available in iTunes 4.5 (untested on iPod) */
     ITDB_SPLACTION_IS_NOT_LESS_THAN = 0x02000040,
-    /* Note: Not available in iTunes 4.5 (seems to work on iPod) */
     ITDB_SPLACTION_IS_NOT_IN_THE_RANGE = 0x02000100,
-
     ITDB_SPLACTION_IS_NOT_IN_THE_LAST = 0x02000200,
+
     ITDB_SPLACTION_IS_NOT = 0x03000001,
     ITDB_SPLACTION_DOES_NOT_CONTAIN = 0x03000002,
-
-    /* Note: Not available in iTunes 4.5 (seems to work on iPod) */
     ITDB_SPLACTION_DOES_NOT_START_WITH = 0x03000004,
-    /* Note: Not available in iTunes 4.5 (seems to work on iPod) */
     ITDB_SPLACTION_DOES_NOT_END_WITH = 0x03000008,
 } ItdbSPLAction;
 
+/**
+ * ItdbSPLFieldType:
+ * @ITDB_SPLFT_STRING:      string
+ * @ITDB_SPLFT_INT:         integer
+ * @ITDB_SPLFT_BOOLEAN:     boolean
+ * @ITDB_SPLFT_DATE:        date
+ * @ITDB_SPLFT_PLAYLIST:    playlist
+ * @ITDB_SPLFT_UNKNOWN:     unknown
+ * @ITDB_SPLFT_BINARY_AND:  binary AND
+ *
+ * Smart Playlist Field Types
+ *
+ * Since: 0.5.0
+ */
 typedef enum
 {
     ITDB_SPLFT_STRING = 1,
@@ -286,6 +482,24 @@ typedef enum
     ITDB_SPLFT_BINARY_AND
 } ItdbSPLFieldType;
 
+/**
+ * ItdbSPLActionType:
+ * @ITDB_SPLAT_STRING:      string
+ * @ITDB_SPLAT_INT:         from integer
+ * @ITDB_SPLAT_DATE:        from date ...
+ * @ITDB_SPLAT_RANGE_INT:   an integer range ...
+ * @ITDB_SPLAT_RANGE_DATE:  a date range ...
+ * @ITDB_SPLAT_INTHELAST:   in the last ...
+ * @ITDB_SPLAT_PLAYLIST:    in playlist
+ * @ITDB_SPLAT_NONE:        none
+ * @ITDB_SPLAT_INVALID:     invalid
+ * @ITDB_SPLAT_UNKNOWN:     unknown
+ * @ITDB_SPLAT_BINARY_AND:  is / is not (binary AND)
+ *
+ * Smart Playlist Action Types
+ *
+ * Since: 0.5.0
+ */
 typedef enum
 {
     ITDB_SPLAT_STRING = 1,
@@ -302,14 +516,23 @@ 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.
+ *
+ * Since: 0.5.0
+ */
 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
@@ -331,84 +554,161 @@ typedef enum {
 #define ITDB_SPLACTION_LAST_SIDEREAL_YEAR 	31558150	// a "sidereal year" is the time it takes the earth to reach the same point in space again, compared to the stars
 #endif
 
-/* Smartlist fields - Used for rules. */
+/**
+ * ItdbSPLField:
+ * @ITDB_SPLFIELD_SONG_NAME:        Song name (string)
+ * @ITDB_SPLFIELD_ALBUM:            Album (string)
+ * @ITDB_SPLFIELD_ARTIST:           Artist (string)
+ * @ITDB_SPLFIELD_BITRATE:          Bitrate (integer, e.g. from/to = 128)
+ * @ITDB_SPLFIELD_SAMPLE_RATE:      Sample rate (integer, e.g. from/to = 44100)
+ * @ITDB_SPLFIELD_YEAR:             Year (integer, e.g. from/to = 2004)
+ * @ITDB_SPLFIELD_GENRE:            Genre (string)
+ * @ITDB_SPLFIELD_KIND:             File type (string, e.g. MP3-File)
+ * @ITDB_SPLFIELD_DATE_MODIFIED:    Date modified (integer, e.g.
+ *                                  from/to = bcf93280 == is before 6/19/2004)
+ * @ITDB_SPLFIELD_TRACKNUMBER:      Track number (integer, e.g. from/to = 2)
+ * @ITDB_SPLFIELD_SIZE:             Size (integer, e.g.
+ *                                  from/to = 0x00600000 for 6MB)
+ * @ITDB_SPLFIELD_TIME:             Time (integer, e.g.
+ *                                  from/to = 83999 for 1:23/83 seconds)
+ * @ITDB_SPLFIELD_COMMENT:          Comment (string)
+ * @ITDB_SPLFIELD_DATE_ADDED:       Date added (integer, e.g.
+ *                                  from/to = bcfa83ff == is after 6/19/2004)
+ * @ITDB_SPLFIELD_COMPOSER:         Composer (string)
+ * @ITDB_SPLFIELD_PLAYCOUNT:        Playcount (integer, e.g. from/to = 1)
+ * @ITDB_SPLFIELD_LAST_PLAYED:      Date last played (integer, e.g.
+ *                                  from = bcfa83ff (6/19/2004)
+ *                                  to = 0xbcfbd57f (6/20/2004))
+ * @ITDB_SPLFIELD_DISC_NUMBER:      Disc number (integer, e.g. from/to = 1)
+ * @ITDB_SPLFIELD_RATING:           Rating (integer, e.g.
+ *                                  from/to = 60 (3 stars))
+ * @ITDB_SPLFIELD_COMPILATION:      Compilation (integer, e.g.
+ *                                  is set -> ITDB_SPLACTION_IS_INT/from=1,
+ *                                  not set -> ITDB_SPLACTION_IS_NOT_INT/from=1)
+ * @ITDB_SPLFIELD_BPM:              Beats per minute (integer, e.g.
+ *                                  from/to = 60)
+ * @ITDB_SPLFIELD_GROUPING:         Grouping (string)
+ * @ITDB_SPLFIELD_PLAYLIST:         FIXME Unknown...not parsed correctly...
+ *                                  from/to = 0xb6fbad5f for "Purchased Music".
+ *                                  Extra data after "to"...
+ * @ITDB_SPLFIELD_VIDEO_KIND:       Logical integer (works on mediatype)
+ * @ITDB_SPLFIELD_TVSHOW:           TV Show (string)
+ * @ITDB_SPLFIELD_SEASON_NR:        Season number (integer)
+ * @ITDB_SPLFIELD_SKIPCOUNT:        Skipcount (integer)
+ * @ITDB_SPLFIELD_LAST_SKIPPED:     Last skipped (integer)
+ * @ITDB_SPLFIELD_ALBUMARTIST:      Album artist (string)
+ *
+ * Smart Playlist Fields, used for Smart Playlist Rules (#Itdb_SPLRule).
+ *
+ * Since: 0.5.0
+ */
 typedef enum {
-    ITDB_SPLFIELD_SONG_NAME = 0x02,    /* String */
-    ITDB_SPLFIELD_ALBUM = 0x03,        /* String */
-    ITDB_SPLFIELD_ARTIST = 0x04,       /* String */
-    ITDB_SPLFIELD_BITRATE = 0x05,      /* Int (e.g. from/to = 128) */
-    ITDB_SPLFIELD_SAMPLE_RATE = 0x06,  /* Int  (e.g. from/to = 44100) */
-    ITDB_SPLFIELD_YEAR = 0x07,         /* Int  (e.g. from/to = 2004) */
-    ITDB_SPLFIELD_GENRE = 0x08,        /* String */
-    ITDB_SPLFIELD_KIND = 0x09,         /* String */
-    ITDB_SPLFIELD_DATE_MODIFIED = 0x0a,/* Int (e.g. from/to = bcf93280 ==
-				     is before 6/19/2004)*/
-    ITDB_SPLFIELD_TRACKNUMBER = 0x0b,  /* Int (e.g. from = 1, to = 2) */
-    ITDB_SPLFIELD_SIZE = 0x0c,         /* Int (e.g. from/to = 0x00600000
-				     for 6MB) */
-    ITDB_SPLFIELD_TIME = 0x0d,         /* Int (e.g. from/to = 83999 for
-				     1:23/83 seconds) */
-    ITDB_SPLFIELD_COMMENT = 0x0e,      /* String */
-    ITDB_SPLFIELD_DATE_ADDED = 0x10,   /* Int (e.g. from/to = bcfa83ff ==
-				     is after 6/19/2004) */
-    ITDB_SPLFIELD_COMPOSER = 0x12,     /* String */
-    ITDB_SPLFIELD_PLAYCOUNT = 0x16,    /* Int  (e.g. from/to = 1) */
-    ITDB_SPLFIELD_LAST_PLAYED = 0x17,  /* Int/ (e.g. from = bcfa83ff (6/19/2004)
-				     to = 0xbcfbd57f (6/20/2004)) */
-    ITDB_SPLFIELD_DISC_NUMBER = 0x18,  /* Int  (e.g. from/to = 1) */
-    ITDB_SPLFIELD_RATING = 0x19,       /* Int/Stars Rating (e.g. from/to =
-                                     60 (3 stars)) */
-    ITDB_SPLFIELD_COMPILATION = 0x1f,  /* Int (e.g. is set ->
-				     ITDB_SPLACTION_IS_INT/from=1,
-				     is not set ->
-				     ITDB_SPLACTION_IS_NOT_INT/from=1) */
-    ITDB_SPLFIELD_BPM = 0x23,          /* Int  (e.g. from/to = 60) */
-    ITDB_SPLFIELD_GROUPING = 0x27,     /* String */
-    ITDB_SPLFIELD_PLAYLIST = 0x28,     /* FIXME - Unknown...not parsed
-				     correctly...from/to = 0xb6fbad5f
-				     for "Purchased Music".  Extra
-				     data after "to"... */
-    ITDB_SPLFIELD_VIDEO_KIND = 0x3c,   /* Logic Int */
-    ITDB_SPLFIELD_TVSHOW = 0x3e,       /* String */
-    ITDB_SPLFIELD_SEASON_NR = 0x3f,    /* Int */
-    ITDB_SPLFIELD_SKIPCOUNT = 0x44,    /* Int */
-    ITDB_SPLFIELD_LAST_SKIPPED = 0x45, /* Int */
-    ITDB_SPLFIELD_ALBUMARTIST = 0x47   /* String */
+    ITDB_SPLFIELD_SONG_NAME = 0x02,
+    ITDB_SPLFIELD_ALBUM = 0x03,
+    ITDB_SPLFIELD_ARTIST = 0x04,
+    ITDB_SPLFIELD_BITRATE = 0x05,
+    ITDB_SPLFIELD_SAMPLE_RATE = 0x06,
+    ITDB_SPLFIELD_YEAR = 0x07,
+    ITDB_SPLFIELD_GENRE = 0x08,
+    ITDB_SPLFIELD_KIND = 0x09,
+    ITDB_SPLFIELD_DATE_MODIFIED = 0x0a,
+    ITDB_SPLFIELD_TRACKNUMBER = 0x0b,
+    ITDB_SPLFIELD_SIZE = 0x0c,
+    ITDB_SPLFIELD_TIME = 0x0d,
+    ITDB_SPLFIELD_COMMENT = 0x0e,
+    ITDB_SPLFIELD_DATE_ADDED = 0x10,
+    ITDB_SPLFIELD_COMPOSER = 0x12,
+    ITDB_SPLFIELD_PLAYCOUNT = 0x16,
+    ITDB_SPLFIELD_LAST_PLAYED = 0x17,
+    ITDB_SPLFIELD_DISC_NUMBER = 0x18,
+    ITDB_SPLFIELD_RATING = 0x19,
+    ITDB_SPLFIELD_COMPILATION = 0x1f,
+    ITDB_SPLFIELD_BPM = 0x23,
+    ITDB_SPLFIELD_GROUPING = 0x27,
+    ITDB_SPLFIELD_PLAYLIST = 0x28,
+    ITDB_SPLFIELD_VIDEO_KIND = 0x3c,
+    ITDB_SPLFIELD_TVSHOW = 0x3e,
+    ITDB_SPLFIELD_SEASON_NR = 0x3f,
+    ITDB_SPLFIELD_SKIPCOUNT = 0x44,
+    ITDB_SPLFIELD_LAST_SKIPPED = 0x45,
+    ITDB_SPLFIELD_ALBUMARTIST = 0x47
 } ItdbSPLField;
 
+/**
+ * Itdb_SPLPref:
+ * @liveupdate:         Live Updating
+ * @checkrules:         Match this number of rules.  If set to 0, ignore rules.
+ * @checklimits:        Limit to this number of @limittype.  If 0, no limits.
+ * @limittype:          an #ItdbLimitType
+ * @limitsort:          an #ItdbLimitSort
+ * @limitvalue:         The value typed next to "Limit type"
+ * @matchcheckedonly:   Match only checked songs
+ * @reserved_int1:      Reserved for future use
+ * @reserved_int2:      Reserved for future use
+ * @reserved1:          Reserved for future use
+ * @reserved2:          Reserved for future use
+ *
+ * Smart Playlist preferences are for various flags that are not strictly smart
+ * playlist "rules."
+ *
+ * Since: 0.5.0
+ */
 struct _Itdb_SPLPref
 {
-    guint8  liveupdate;        /* "live Updating" check box */
-    guint8  checkrules;        /* "Match X of the following
-				  conditions" check box */
-    guint8  checklimits;       /* "Limit To..." check box */
-    guint32 limittype;         /* See types defined above */
-    guint32 limitsort;         /* See types defined above */
-    guint32 limitvalue;        /* The value typed next to "Limit
-				  type" */
-    guint8  matchcheckedonly;  /* "Match only checked songs" check box */
-    /* reserved for future use */
+    guint8  liveupdate;
+    guint8  checkrules;
+    guint8  checklimits;
+    guint32 limittype;
+    guint32 limitsort;
+    guint32 limitvalue;
+    guint8  matchcheckedonly;
     gint32 reserved_int1;
     gint32 reserved_int2;
     gpointer reserved1;
     gpointer reserved2;
 };
 
+/**
+ * Itdb_SPLRule:
+ * @field:          an #ItdbSPLFieldType
+ * @action:         an #ItdbSPLActionType
+ * @string:         data in UTF8
+ * @fromvalue:      from value
+ * @fromdate:       from date
+ * @fromunits:      from units
+ * @tovalue:        to value
+ * @todate:         to date
+ * @tounits:        to units
+ * @unk052:         Unknown
+ * @unk056:         Unknown
+ * @unk060:         Unknown
+ * @unk064:         Unknown
+ * @unk068:         Unknown
+ * @reserved_int1:  Reserved for future use
+ * @reserved_int2:  Reserved for future use
+ * @reserved1:      Reserved for future use
+ * @reserved2:      Reserved for future use
+ *
+ * Smart Playlist Rule
+ *
+ * The from and to fields require some explanation.  If @field is a date type,
+ * then @value would be set to 0x2dae2dae2dae2dae, @date would be a number,
+ * (e.g. 2 or -2), and @units would be a time unit in seconds (e.g. one week
+ * would be 604800).  If @field is an integer comparison, like rating = 60 (i.e.
+ * 3 stars), then @value would be the value we care about (e.g. 60), @date would
+ * be 0, and @units would be 1.  Binary AND types are similar, @value is the
+ * important part, with @date = 0 and @units = 1.  Clear as mud, right?
+ *
+ * For more details see <ulink
+ * url="http://ipodlinux.org/ITunesDB.html&num;Smart_Playlist_Rule_Values">ipodlinux.org</ulink>.
+ *
+ * Since: 0.5.0
+ */
 struct _Itdb_SPLRule
 {
     guint32 field;
     guint32 action;
-    gchar *string;             /* data in UTF8  */
-    /* from and to are pretty stupid.. if it's a date type of field,
-       then
-         value = 0x2dae2dae2dae2dae,
-         date = some number, like 2 or -2
-         units = unit in seconds, like 604800 = a week
-       but if this is actually some kind of integer comparison, like
-       rating = 60 (3 stars)
-         value = the value we care about
-	 date = 0
-	 units = 1 */
+    gchar *string;
     guint64 fromvalue;
     gint64 fromdate;
     guint64 fromunits;
@@ -427,12 +727,25 @@ struct _Itdb_SPLRule
     gpointer reserved2;
 };
 
-
+/**
+ * Itdb_SPLRules:
+ * @unk004:         Unknown
+ * @match_operator: Whether all rules must match (#ITDB_SPLMATCH_AND) or any
+ *                  rules may match (#ITDB_SPLMATCH_OR)
+ * @rules:          list of #Itdb_SPLRule's
+ * @reserved_int1:  Reserved for future use
+ * @reserved_int2:  Reserved for future use
+ * @reserved1:      Reserved for future use
+ * @reserved2:      Reserved for future use
+ *
+ * Smart Playlist Rules
+ *
+ * Since: 0.5.0
+ */
 struct _Itdb_SPLRules
 {
     guint32 unk004;
-    guint32 match_operator;  /* "All" (logical AND): Itdb_SPLMATCH_AND,
-				"Any" (logical OR): Itdb_SPLMATCH_OR */
+    guint32 match_operator;
     GList *rules;
     /* reserved for future use */
     gint32 reserved_int1;
@@ -448,10 +761,24 @@ 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
+ *
+ * Since: 0.7.0
+ */
 struct _Itdb_Chapter
 {
     guint32 startpos;
-    gchar *chaptertitle;          /* data in UTF8  */
+    gchar *chaptertitle;
     /* reserved for future use */
     gint32 reserved_int1;
     gint32 reserved_int2;
@@ -459,7 +786,21 @@ 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
+ *
+ * Since: 0.7.0
+ */
 struct _Itdb_Chapterdata
 {
     GList *chapters;
@@ -480,25 +821,52 @@ 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
+ *
+ * Since: 0.3.0
+ */
 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 +880,29 @@ 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
+ *
+ * Since: 0.4.0
+ */
 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 +916,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 +956,62 @@ 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
+ *
+ * Since: 0.4.0
+ */
 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 +1028,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 +1097,39 @@ 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
+ *
+ * Since: 0.1.3
+ */
 typedef enum
 {
     ITDB_PSO_MANUAL = 1,
@@ -693,7 +1163,23 @@ 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.
+ *
+ * Since: 0.5.0
+ */
 typedef enum
 {
     ITDB_MEDIATYPE_AUDIO      = 0x0001,
@@ -704,35 +1190,331 @@ typedef enum
     ITDB_MEDIATYPE_TVSHOW     = 0x0040,
 } Itdb_Mediatype;
 
-/* some of the descriptive comments below are copied verbatim from
-   http://ipodlinux.org/ITunesDB. 
-   http://ipodlinux.org/ITunesDB is the best source for information
-   about the iTunesDB and related files. */
+/**
+ * Itdb_Track:
+ * @itdb:                       A pointer to the #Itdb_iTunesDB (for convenience)
+ * @title:                      The title of the track in UTF8
+ * @ipod_path:                  The file path on the iPod.  Directories are
+ *                              separated with ":" instead of "/".  The path is
+ *                              relative to the iPod mountpoint.
+ * @album:                      The album name in UTF8
+ * @artist:                     The artist name in UTF8
+ * @genre:                      The genre in UTF8
+ * @filetype:                   A UTF8 string describing the file type.  E.g.
+ *                              "MP3-File".
+ * @comment:                    A comment in UTF8
+ * @category:                   The category ("Technology", "Music", etc.)
+ *                              where the podcast was located.  (Added in
+ *                              dbversion 0x0d)
+ * @composer:                   The composer name in UTF8
+ * @grouping:                   ??? (UTF8)
+ * @description:                Description text (such as podcast show notes).
+ *                              (Added in dbversion 0x0d)
+ * @podcasturl:                 Podcast Enclosure URL in UTF-8 or ASCII.
+ *                              (Added in dbversion 0x0d)
+ * @podcastrss:                 Podcast RSS URL in UTF-8 or ASCII.
+ *                              (Added in dbversion 0x0d)
+ * @chapterdata:                This is an m4a-style entry that is used to
+ *                              display subsongs within a mhit.  (Added in
+ *                              dbversion 0x0d)
+ * @subtitle:                   Subtitle (usually the same as Description).
+ *                              (Added in dbversion 0x0d)
+ * @tvshow:                     Name of the TV show (only used for TV Shows).
+ *                              (Added in dbversion 0x0d?) (Since libgpod-0.4.2)
+ * @tvepisode:                  The episode number (only used for TV Shows).
+ *                              (Added in dbversion 0x0d?) (Since libgpod-0.4.2)
+ * @tvnetwork:                  The TV network (only used for TV Shows).
+ *                              (Added in dbversion 0x0d?) (Since libgpod-0.4.2)
+ * @albumartist:                The album artist (Added in dbversion 0x13?)
+ *                              (Since libgpod-0.4.2)
+ * @keywords:                   List of keywords pertaining to the track.
+ *                              (Added in dbversion 0x13?) (Since libgpod-0.4.2)
+ * @sort_artist:                The artist name used for sorting.  Artists with
+ *                              names like "The Artist" would have "Artist,
+ *                              The" here.  If you do not set this field,
+ *                              libgpod will pre-sort the lists displayed by
+ *                              the iPod according to "Artist, The", without
+ *                              setting this field.
+ *                              (Added in dbversion 0x13?) (Since libgpod-0.5.0)
+ * @sort_title:                 The track title used for sorting.  See
+ *                              @sort_artist. (Since libgpod-0.5.0)
+ * @sort_album:                 The album name used for sorting.  See
+ *                              @sort_artist. (Since libgpod-0.5.0)
+ * @sort_albumartist:           The album artist used for sorting.  See
+ *                              @sort_artist. (Since libgpod-0.5.0)
+ * @sort_composer:              The composer used for sorting.  See
+ *                              @sort_artist. (Since libgpod-0.5.0)
+ * @sort_tvshow:                The name of the TV show used for sorting.  See
+ *                              @sort_artist. (Since libgpod-0.5.0)
+ * @id:                         Unique ID of track
+ * @size:                       The size of the file in bytes
+ * @tracklen:                   The length of the track in ms
+ * @cd_nr:                      The CD number the track comes from.
+ * @cds:                        The total number of CDs.
+ * @track_nr:                   The track number.
+ * @tracks:                     The total number of tracks.
+ * @bitrate:                    The bitrate at which the file is encoded.
+ * @samplerate:                 The samplerate of the track (e.g. CD = 44100)
+ * @samplerate_low:             In the iTunesDB the samplerate is
+ *                              multiplied by 0x10000 -- these are the
+ *                              lower 16 bit, which are usually 0
+ * @year:                       The year the track was released
+ * @volume:                     Volume adjustment field.  This is a value from
+ *                              -255 to 255 that will be applied to the track
+ *                              on playback.
+ * @soundcheck:                 The SoundCheck value to apply to the song, when
+ *                              SoundCheck is switched on in the iPod settings.
+ *                              The value for this field can be determined by
+ *                              the equation: X = 1000 * 10 ^ (-.1 * Y) where Y
+ *                              is the adjustment value in dB and X is the
+ *                              value that goes into the SoundCheck field. The
+ *                              value 0 is special, the equation is not used
+ *                              and it is treated as "no Soundcheck" (basically
+ *                              the same as the value 1000). This equation
+ *                              works perfectly well with ReplayGain derived
+ *                              data instead of the iTunes SoundCheck derived
+ *                              information.
+ * @time_added:                 The time the track was added.
+ * @time_modified:              The time the track was last modified
+ * @time_played:                The time the track was last played
+ * @bookmark_time:              The time, in milliseconds, that the track will
+ *                              start playing at. This is used for AudioBook
+ *                              filetypes (.aa and .m4b).  Note that there is
+ *                              also a bookmark value in the play counts file
+ *                              that will be set by the iPod and can be used
+ *                              instead of this value.
+ * @rating:                     The track rating (stars * #ITDB_RATING_STEP)
+ * @playcount:                  The number of times the track has been played
+ * @playcount2:                 This also stores the play count of the
+ *                              track.  It is unclear if this ever differs
+ *                              from the above value. During sync, this is set
+ *                              to the same value as @playcount.
+ * @recent_playcount:           The number of times the track was played since
+ *                              the last sync.
+ * @transferred:                Whether the file been transferred to iPod.
+ * @BPM:                        BPM (beats per minute) of the track
+ * @app_rating:                 The last rating set by an application (e.g.
+ *                              iTunes).  If the rating on the iPod and the
+ *                              @rating field above differ, the original
+ *                              rating is copied here and the new rating is
+ *                              stored in @rating.
+ * @type1:                      CBR MP3s and AAC are 0x00, VBR MP3s are 0x01
+ * @type2:                      MP3s are 0x01, AAC are 0x00
+ * @compilation:                Flag to mark the track as a compilation.  True
+ *                              if set to 0x1, false if set to 0x0.
+ * @starttime:                  The time, in milliseconds, at which the song
+ *                              will start playing.
+ * @stoptime:                   The time, in milliseconds, at which the song
+ *                              will stop playing.
+ * @checked:                    Flag for whether the track is checked.  True if
+ *                              set to 0x0, false if set to 0x1
+ * @dbid:                       Unique database ID that identifies this song
+ *                              across the databases on the iPod. For example,
+ *                              this id joins an iTunesDB mhit with an
+ *                              ArtworkDB mhii.
+ * @drm_userid:                 Apple Store/Audible User ID (for DRM'ed files
+ *                              only, set to 0 otherwise).
+ * @visible:                    If this value is 1, the song is visible on the
+ *                              iPod. All other values cause the file to be
+ *                              hidden.
+ * @filetype_marker:            This appears to always be 0 on hard drive based
+ *                              iPods, but for the iTunesDB that is written to
+ *                              an iPod Shuffle, iTunes 4.7.1 writes out the
+ *                              file's type as an ANSI string(!). For example,
+ *                              a MP3 file has a filetype of 0x4d503320 ->
+ *                              0x4d = 'M', 0x50 = 'P', 0x33 = '3', 0x20 =
+ *                              &lt;space&gt;.  This is set to the filename
+ *                              extension by libgpod when copying the track to
+ *                              the iPod.
+ * @artwork_count:              The number of album artwork items associated
+ *                              with this song.  libgpod updates this value
+ *                              when syncing.
+ * @artwork_size:               The total size of artwork (in bytes) attached
+ *                              to this song, when it is converted to JPEG
+ *                              format. Observed in dbversion 0x0b and with
+ *                              an iPod Photo. libgpod updates this value when
+ *                              syncing.
+ * @samplerate2:                The sample rate of the song expressed as an
+ *                              IEEE 32 bit floating point number.  It is
+ *                              uncertain why this is here.  libgpod will set
+ *                              this when adding a track.
+ * @unk126:                     Unknown, but always seems to be 0xffff for
+ *                              MP3/AAC songs, 0x0 for uncompressed songs
+ *                              (like WAVE format), 0x1 for Audible.  libgpod
+ *                              will try to set this when adding a new track.
+ * @unk132:                     Unknown
+ * @time_released:              The date/time the track was added to the iTunes
+ *                              music store?  For podcasts this is the release
+ *                              date that is displayed next to the title in the
+ *                              Podcast playlist.
+ * @unk144:                     Unknown, but MP3 songs appear to be always
+ *                              0x000c, AAC songs are always 0x0033, Audible
+ *                              files are 0x0029, WAV files are 0x0.  libgpod
+ *                              will attempt to set this value when adding a
+ *                              track.
+ * @explicit_flag:              Flag to mark a track as "explicit" in iTunes.
+ *                              True if to 0x1, false if set to 0x0.
+ * @unk148:                     Unknown - used for Apple Store DRM songs
+ *                              (always 0x01010100?), zero otherwise
+ * @unk152:                     Unknown
+ * @skipcount:                  The number of times the track has been skipped.
+ *                              (Added in dbversion 0x0c)
+ * @recent_skipcount:           The number of times the track was skipped since
+ *                              the last sync.
+ * @last_skipped:               The time the track was last skipped.  (Added in
+ *                              dbversion 0x0c)
+ * @has_artwork:                Whether the track has artwork.
+ *                              True if set to 0x01, false if set to 0x02.
+ * @skip_when_shuffling:        Flag to skip the track when shuffling.  True if
+ *                              set to 0x01, false if set to 0x00. Audiobooks
+ *                              (.aa and .m4b) always seem to be skipped when
+ *                              shuffling, regardless of this flag.
+ * @remember_playback_position: Flag to remember playback position.
+ *                              True when set to 0x01, false when set to 0x00.
+ *                              Audiobooks (.aa and .m4b) always seem to
+ *                              remember the playback position, regardless of
+ *                              this flag.
+ * @flag4:                      Used for podcasts, 0x00 otherwise.  If set to
+ *                              0x01 the "Now Playing" page will show
+ *                              Title/Album, when set to 0x00 it will also show
+ *                              the Artist.  When set to 0x02 a sub-page
+ *                              (middle button) with further information about
+ *                              the track will be shown.
+ * @dbid2:                      The purpose of the field is unclear.  If not
+ *                              set, libgpod will set this to the same value as
+ *                              @dbid when adding a track.  (With iTunes, since
+ *                              dbversion 0x12, this field value differs from
+ *                              @dbid.)
+ * @lyrics_flag:                Whether the track has lyrics (e.g. it has a
+ *                              USLT ID3 tag in an MP3 or a @lyr atom in an
+ *                              MP4).  True if set to 0x01, false if set to
+ *                              0x00.
+ * @movie_flag:                 Whether the track is a movie.  True if set to
+ *                              0x01, false if set to 0x00.
+ * @mark_unplayed:              A value of 0x02 marks a podcast as unplayed on
+ *                              the iPod, with a bullet.  Once played it is set
+ *                              to 0x01. Non-podcasts have this set to 0x01.
+ *                              (Added in dbversion 0x0c)
+ * @unk179:                     Unknown, always 0x00 so far.  (Added in
+ *                              dbversion 0x0c)
+ * @unk180:                     Unknown.  (Added in dbversion 0x0c)
+ * @pregap:                     The number of samples of silence before the
+ *                              track starts (for gapless playback).
+ * @samplecount:                The number of samples in the track (for gapless
+ *                              playback).
+ * @unk196:                     Unknown.  (Added in dbversion 0x0c)
+ * @postgap:                    The number of samples of silence at the end of
+ *                              the track (for gapless playback).
+ * @unk204:                     Unknown.  Appears to be 0x1 for files encoded
+ *                              using the MP3 encoder, 0x0 otherwise.  (Added
+ *                              in dbversion 0x0c, first values observed in
+ *                              0x0d.)
+ * @mediatype:                  The type of file.  It must be set to 0x00000001
+ *                              for audio files, and set to 0x00000002 for
+ *                              video files.  If set to 0x00, the files show up
+ *                              in both, the audio menus ("Songs", "Artists",
+ *                              etc.) and the video menus ("Movies", "Music
+ *                              Videos", etc.).  It appears to be set to 0x20
+ *                              for music videos, and if set to 0x60 the file
+ *                              shows up in "TV Shows" rather than "Movies".
+ *                              <para>
+ *                              The following list summarizes all observed types:
+ *                              </para>
+ *                              <itemizedlist>
+ *                              <listitem>0x00 00 00 00 - Audio/Video</listitem>
+ *                              <listitem>0x00 00 00 01 - Audio</listitem>
+ *                              <listitem>0x00 00 00 02 - Video</listitem>
+ *                              <listitem>0x00 00 00 04 - Podcast</listitem>
+ *                              <listitem>0x00 00 00 06 - Video Podcast</listitem>
+ *                              <listitem>0x00 00 00 08 - Audiobook</listitem>
+ *                              <listitem>0x00 00 00 20 - Music Video</listitem>
+ *                              <listitem>0x00 00 00 40 - TV Show (shows up ONLY
+ *                              in TV Shows)</listitem>
+ *                              <listitem>0x00 00 00 60 - TV Show (shows up in
+ *                              the Music lists as well)</listitem>
+ *                              </itemizedlist>
+ * @season_nr:                  The season number of the track (only used for
+ *                              TV Shows).
+ * @episode_nr:                 The episode number of the track (only used for
+ *                              TV Shows).  Although this is not displayed on
+ *                              the iPod, the episodes are sorted by episode
+ *                              number.
+ * @unk220:                     Unknown.  This has something to do with
+ *                              protected files.  It is set to 0x0 for
+ *                              non-protected files.
+ * @unk224:                     Unknown.  (Added in dbversion 0x0c)
+ * @unk228:                     Unknown.  (Added in dbversion 0x0c)
+ * @unk232:                     Unknown.  (Added in dbversion 0x0c)
+ * @unk236:                     Unknown.  (Added in dbversion 0x0c)
+ * @unk240:                     Unknown.  (Added in dbversion 0x0c)
+ * @unk244:                     Unknown.  (Added in dbversion 0x13)
+ * @gapless_data:               The size in bytes from first Synch Frame
+ *                              (which is usually the XING frame that
+ *                              includes the LAME tag) until the 8th before
+ *                              the last frame. The gapless playback does not
+ *                              work for MP3 files if this is set to zero. For
+ *                              AAC tracks, this may be zero.  (Added in
+ *                              dbversion 0x13)
+ * @unk252:                     Unknown.  (Added in dbversion 0x0c)
+ * @gapless_track_flag:         If set to 1, this track has gapless playback
+ *                              data.  (Added in dbversion 0x13)
+ * @gapless_album_flag:         If set to 1, this track does not use
+ *                              crossfading in iTunes.  (Added in dbversion
+ *                              0x13)
+ * @artwork:                    An #Itdb_Artwork for cover art
+ * @mhii_link:                  This is set to the id of the corresponding
+ *                              ArtworkDB mhii, used for sparse artwork
+ *                              support.  (Since libgpod-0.7.0)
+ * @reserved_int1:              Reserved for future use
+ * @reserved_int2:              Reserved for future use
+ * @reserved_int3:              Reserved for future use
+ * @reserved_int4:              Reserved for future use
+ * @reserved_int5:              Reserved for future use
+ * @reserved_int6:              Reserved for future use
+ * @reserved1:                  Reserved for future use
+ * @reserved2:                  Reserved for future use
+ * @reserved3:                  Reserved for future use
+ * @reserved4:                  Reserved for future use
+ * @reserved5:                  Reserved for future use
+ * @reserved6:                  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 a track in an iTunesDB
+ *
+ * <note><para>When adding string fields don't forget to add them in
+ * itdb_track_duplicate() as well.</para></note>
+ *
+ * Many of the parameter descriptions are copied verbatim from
+ * http://ipodlinux.org/ITunesDB, which is the best source for information about
+ * the iTunesDB and related files.
+ */
 struct _Itdb_Track
 {
-  Itdb_iTunesDB *itdb;       /* pointer to iTunesDB (for convenience)   */
-  gchar   *title;            /* title (utf8)                            */
-  gchar   *ipod_path;        /* name of file on iPod: uses ":" instead
-				of "/" and is relative to mountpoint    */
-  gchar   *album;            /* album (utf8)                            */
-  gchar   *artist;           /* artist (utf8)                           */
-  gchar   *genre;            /* genre (utf8)                            */
-  gchar   *filetype;         /* eg. "MP3-File"...(utf8)                 */
-  gchar   *comment;          /* comment (utf8)                          */
-  gchar   *category;         /* Category for podcast                    */
-  gchar   *composer;         /* Composer (utf8)                         */
-  gchar   *grouping;         /* ? (utf8)                                */
-  gchar   *description;      /* see note for MHOD_ID in itdb_itunesdb.c */
-  gchar   *podcasturl;       /* see note for MHOD_ID in itdb_itunesdb.c */
-  gchar   *podcastrss;       /* see note for MHOD_ID in itdb_itunesdb.c */
-  Itdb_Chapterdata *chapterdata; /* see note for MHOD_ID in itdb_itunesdb.c */
-  gchar   *subtitle;         /* see note for MHOD_ID in itdb_itunesdb.c */
-/* the following 6 are new in libgpod 0.4.2... */
-  gchar   *tvshow;           /* see note for MHOD_ID in itdb_itunesdb.c */
-  gchar   *tvepisode;        /* see note for MHOD_ID in itdb_itunesdb.c */
-  gchar   *tvnetwork;        /* see note for MHOD_ID in itdb_itunesdb.c */
-  gchar   *albumartist;      /* see note for MHOD_ID in itdb_itunesdb.c */
-  gchar   *keywords;         /* see note for MHOD_ID in itdb_itunesdb.c */
+  Itdb_iTunesDB *itdb;
+  gchar   *title;
+  gchar   *ipod_path;
+  gchar   *album;
+  gchar   *artist;
+  gchar   *genre;
+  gchar   *filetype;
+  gchar   *comment;
+  gchar   *category;
+  gchar   *composer;
+  gchar   *grouping;
+  gchar   *description;
+  gchar   *podcasturl;
+  gchar   *podcastrss;
+  Itdb_Chapterdata *chapterdata;
+  gchar   *subtitle;
+/* the following 5 are new in libgpod 0.4.2... */
+  gchar   *tvshow;
+  gchar   *tvepisode;
+  gchar   *tvnetwork;
+  gchar   *albumartist;
+  gchar   *keywords;
 /* the following 6 are new in libgpod 0.5.0... */
   /* You can set these strings to override the standard
      sortorder. When set they take precedence over the default
@@ -747,199 +1529,90 @@ struct _Itdb_Track
      the lists displayed by the iPod according to "Artist, The",
      without setting the field.
   */
-  gchar   *sort_artist;      /* artist (for sorting)                    */
-  gchar   *sort_title;       /* title (for sorting)                     */
-  gchar   *sort_album;       /* album (for sorting)                     */
-  gchar   *sort_albumartist; /* album artist (for sorting)              */
-  gchar   *sort_composer;    /* composer (for sorting)                  */
-  gchar   *sort_tvshow;      /* tv show (for sorting)                   */
-/* new fields in libgpod 0.5.0 up to here */
-  guint32 id;                /* unique ID of track                      */
-  gint32  size;              /* size of file in bytes                   */
-  gint32  tracklen;          /* Length of track in ms                   */
-  gint32  cd_nr;             /* CD number                               */
-  gint32  cds;               /* number of CDs                           */
-  gint32  track_nr;          /* track number                            */
-  gint32  tracks;            /* number of tracks                        */
-  gint32  bitrate;           /* bitrate                                 */
-  guint16 samplerate;        /* samplerate (CD: 44100)                  */
-  guint16 samplerate_low;    /* in the iTunesDB the samplerate is
-                                multiplied by 0x10000 -- these are the
-				lower 16 bit, which are usually 0       */
-  gint32  year;              /* year                                    */
-  gint32  volume;            /* volume adjustment                       */
-  guint32 soundcheck;        /* volume adjustment "soundcheck"          */
-  time_t  time_added;        /* time when added                         */
-  time_t  time_modified;     /* time of last modification               */
-  time_t  time_played;       /* time of last play                       */
-  guint32 bookmark_time;     /* bookmark set for (AudioBook) in ms      */
-  guint32 rating;            /* star rating (stars * RATING_STEP (20))  */
-  guint32 playcount;         /* number of times track was played        */
-  guint32 playcount2;        /* Also stores the play count of the
-				song.  Don't know if it ever differs
-				from the above value. During sync itdb
-				sets playcount2 to the same value as
-				playcount.                              */
-  guint32 recent_playcount;  /* times track was played since last sync  */
-  gboolean transferred;      /* has file been transferred to iPod?      */
-  gint16  BPM;               /* BPM (beats per minute) of this track    */
-  guint8  app_rating;        /* star rating set by appl. (not
-			      * iPod). If the rating set on the iPod
-			        and the rating field above differ, the
-				original rating is copied here and the
-				new rating is stored above. */
-  guint8  type1;             /* CBR MP3s and AAC are 0x00, VBR MP3s are
-			        0x01                                    */
-  guint8  type2;             /* MP3s are 0x01, AAC are 0x00             */
+  gchar   *sort_artist;
+  gchar   *sort_title;
+  gchar   *sort_album;
+  gchar   *sort_albumartist;
+  gchar   *sort_composer;
+  gchar   *sort_tvshow;
+/* end of new fields in libgpod 0.5.0 */
+  guint32 id;
+  gint32  size;
+  gint32  tracklen;
+  gint32  cd_nr;
+  gint32  cds;
+  gint32  track_nr;
+  gint32  tracks;
+  gint32  bitrate;
+  guint16 samplerate;
+  guint16 samplerate_low;
+  gint32  year;
+  gint32  volume;
+  guint32 soundcheck;
+  time_t  time_added;
+  time_t  time_modified;
+  time_t  time_played;
+  guint32 bookmark_time;
+  guint32 rating;
+  guint32 playcount;
+  guint32 playcount2;
+  guint32 recent_playcount;
+  gboolean transferred;
+  gint16  BPM;
+  guint8  app_rating;
+  guint8  type1;
+  guint8  type2;
   guint8  compilation;
   guint32 starttime;
   guint32 stoptime;
-  guint8  checked;           /* 0x0: checkmark on track is set 0x1: not set */
-  guint64 dbid;              /* unique database ID                      */
-  guint32 drm_userid;        /* Apple Store/Audible User ID (for DRM'ed
-				files only, set to 0 otherwise).        */
-  guint32 visible;           /*  If this value is 1, the song is visible
-				 on the iPod. All other values cause
-				 the file to be hidden.                 */
-  guint32 filetype_marker;   /* This appears to always be 0 on hard
-                                drive based iPods, but for the
-                                iTunesDB that is written to an iPod
-                                Shuffle, iTunes 4.7.1 writes out the
-                                file's type as an ANSI string(!). For
-                                example, a MP3 file has a filetype of
-                                0x4d503320 -> 0x4d = 'M', 0x50 = 'P',
-                                0x33 = '3', 0x20 = <space>. (set to
-				the filename extension by itdb when
-				copying track to iPod)                  */
-  guint16 artwork_count;     /* The number of album artwork items
-				associated with this song. libgpod
-				updates this value when syncing */
-  guint32 artwork_size;      /* The total size of artwork (in bytes)
-				attached to this song, when it is
-				converted to JPEG format. Observed in
-				iPodDB version 0x0b and with an iPod
-				Photo. libgpod updates this value when
-				syncing                                 */
-  float samplerate2;         /* The sample rate of the song expressed
-				as an IEEE 32 bit floating point
-				number.  It's uncertain why this is
-				here.  itdb will set this when adding
-				a track                                 */
-
-  guint16 unk126;     /* unknown, but always seems to be 0xffff for
-			 MP3/AAC songs, 0x0 for uncompressed songs
-			 (like WAVE format), 0x1 for Audible. itdb
-			 will try to set this when adding a new track */
-  guint32 unk132;     /* unknown */
-  time_t  time_released;/* date/time added to music store? 
-			   For podcasts: release date as displayed next to the 
-			   title in the Podcast playlist */
-  guint16 unk144;     /* unknown, but MP3 songs appear to be always
-			 0x000c, AAC songs are always 0x0033, Audible
-			 files are 0x0029, WAV files are 0x0. itdb
-			 will attempt to set this value when adding a
-			 track. */ 
-  guint16 explicit_flag;/* If this flag is set to 1, the track is shown as
-			   explicit content in iTunes. Otherwise set this flag
-			   to 0.*/
-  guint32 unk148;     /* unknown - used for Apple Store DRM songs
-			 (always 0x01010100?), zero otherwise */
-  guint32 unk152;     /* unknown */
-  guint32 skipcount;  /* Number of times the track has been skipped.
-			 Formerly unk156 (added in dbversion 0x0c) */
-  guint32 recent_skipcount; /* number of times track was skipped since
-			       last sync */
-  guint32 last_skipped;/* Date/time last skipped. Formerly unk160
-			 (added in dbversion 0x0c) */
-  guint8 has_artwork; /* 0x01: artwork is present. 0x02: no artwork is
-			 present for this track (used by the iPod to
-			 decide whether to display Artwork or not) */
-  guint8 skip_when_shuffling;/* "Skip when shuffling" when set to
-			 0x01, set to 0x00 otherwise. .m4b and .aa
-			 files always seem to be skipped when
-			 shuffling, however */
-  guint8 remember_playback_position;/* "Remember playback position"
-			 when set to 0x01, set to 0x00 otherwise. .m4b
-			 and .aa files always seem to remember the
-			 playback position, however. */
-  guint8 flag4;       /* Used for podcasts, 0x00 otherwise.  If set to
-			 0x01 the "Now Playing" page will show
-			 Title/Album, when set to 0x00 it will also
-			 show the Artist. When set to 0x02 a sub-page
-			 (middle button) with further information
-			 about the track will be shown. */
-  guint64 dbid2;      /* not clear. if not set, itdb will set this to
-			 the same value as dbid when adding a
-			 track. (With iTunes, since V0x12, this field
-			 value differs from the dbid one.) */
-  guint8 lyrics_flag; /* set to 0x01 if lyrics are present in MP3 tag
-			 ("ULST"), 0x00 otherwise */
-  guint8 movie_flag;  /* set to 0x01 if it's a movie file, 0x00
-		         otherwise */
-  guint8 mark_unplayed; /* A value of 0x02 marks a podcast as unplayed
-			   on the iPod (bullet) once played it is set to
-			   0x01. Non-podcasts have this set to 0x01. */
-  guint8 unk179;      /* unknown (always 0x00 so far) */
+  guint8  checked;
+  guint64 dbid;
+  guint32 drm_userid;
+  guint32 visible;
+  guint32 filetype_marker;
+  guint16 artwork_count;
+  guint32 artwork_size;
+  float samplerate2;
+  guint16 unk126;
+  guint32 unk132;
+  time_t  time_released;
+  guint16 unk144;
+  guint16 explicit_flag;
+  guint32 unk148;
+  guint32 unk152;
+  guint32 skipcount;
+  guint32 recent_skipcount;
+  guint32 last_skipped;
+  guint8 has_artwork;
+  guint8 skip_when_shuffling;
+  guint8 remember_playback_position;
+  guint8 flag4;
+  guint64 dbid2;
+  guint8 lyrics_flag;
+  guint8 movie_flag;
+  guint8 mark_unplayed;
+  guint8 unk179;
   guint32 unk180;
-  guint32 pregap;     /* Number of samples of silence before the songs
-			 starts (for gapless playback). */
-  guint64 samplecount;/* Number of samples in the song. First observed
-			 in dbversion 0x0d, and only for AAC and WAV
-			 files (for gapless playback). */
+  guint32 pregap;
+  guint64 samplecount;
   guint32 unk196;
-  guint32 postgap;    /* Number of samples of silence at the end of
-			 the song (for gapless playback). */
-  guint32 unk204;     /* unknown - added in dbversion 0x0c, first
-			 values observed in 0x0d. Observed to be 0x0
-			 or 0x1. */
-  guint32 mediatype;  /* It seems that this field denotes the type of
-		         the file on (e.g.) the 5g video iPod. It must
-			 be set to 0x00000001 for audio files, and set
-			 to 0x00000002 for video files. If set to
-			 0x00, the files show up in both, the audio
-			 menus ("Songs", "Artists", etc.) and the
-			 video menus ("Movies", "Music Videos",
-			 etc.). It appears to be set to 0x20 for music
-			 videos, and if set to 0x60 the file shows up
-			 in "TV Shows" rather than "Movies". 
-
-			 The following list summarizes all observed types:
-
-			 * 0x00 00 00 00 - Audio/Video
-			 * 0x00 00 00 01 - Audio
-			 * 0x00 00 00 02 - Video
-			 * 0x00 00 00 04 - Podcast
-			 * 0x00 00 00 06 - Video Podcast
-			 * 0x00 00 00 08 - Audiobook
-			 * 0x00 00 00 20 - Music Video
-			 * 0x00 00 00 40 - TV Show (shows up ONLY in TV Shows
-			 * 0x00 00 00 60 - TV Show (shows up in the
-			                            Music lists as well) */
-  guint32 season_nr;  /* the season number of the track, for TV shows only. */
-  guint32 episode_nr; /* the episode number of the track, for TV shows
-			 only - although not displayed on the iPod,
-			 the episodes are sorted by episode number. */
-  guint32 unk220;     /* Has something to do with protected files -
-			 set to 0x0 for non-protected files. */
+  guint32 postgap;
+  guint32 unk204;
+  guint32 mediatype;
+  guint32 season_nr;
+  guint32 episode_nr;
+  guint32 unk220;
   guint32 unk224;
   guint32 unk228, unk232, unk236, unk240, unk244;
-  guint32 gapless_data;/* some magic number needed for gapless playback
-			  (added in dbversion 0x13) It has been observed
-			  that gapless playback does not work if this is
-			  set to zero. This number is related to the the
-			  filesize in bytes, but it is a couple of bytes
-			  less than the filesize. Maybe ID3 tags
-			  etc... taken off? */
+  guint32 gapless_data;
   guint32 unk252;
-  guint16 gapless_track_flag; /* if 1, this track has gapless playback data
-			         (added in dbversion 0x13) */
-  guint16 gapless_album_flag; /* if 1, this track does not use crossfading
-			         in iTunes (added in dbversion 0x13) */
+  guint16 gapless_track_flag;
+  guint16 gapless_album_flag;
 
   /* This is for Cover Art support */
   struct _Itdb_Artwork *artwork;
 
-    /* 200805 */
+  /* This is for sparse artwork support, new in libgpod-0.7.0 */
   guint32 mhii_link;
 
   /* reserved for future use */
@@ -977,13 +1650,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;
 
 
@@ -1197,9 +1881,9 @@ gpointer itdb_artwork_get_pixbuf (Itdb_Device *device, Itdb_Artwork *artwork,
 
 /* itdb_thumb_... */
 Itdb_Thumb *itdb_thumb_duplicate (Itdb_Thumb *thumb);
-gpointer itdb_thumb_to_pixbuf_at_size (Itdb_Device *dev, Itdb_Thumb *thumb,  
-                                       gint width, gint height); 
-GList *itdb_thumb_to_pixbufs (Itdb_Device *dev, Itdb_Thumb *thumb); 
+gpointer itdb_thumb_to_pixbuf_at_size (Itdb_Device *device, Itdb_Thumb *thumb,
+                                       gint width, gint height);
+GList *itdb_thumb_to_pixbufs (Itdb_Device *device, Itdb_Thumb *thumb);
 void itdb_thumb_free (Itdb_Thumb *thumb);
 
 /* itdb_chapterdata_... */
diff --git a/src/itdb_artwork.c b/src/itdb_artwork.c
index db895d7..dd6c4ca 100644
--- a/src/itdb_artwork.c
+++ b/src/itdb_artwork.c
@@ -48,9 +48,11 @@
  *
  * Creates a new #Itdb_Artwork
  *
- * Return value: a new #Itdb_Artwork to be freed with itdb_artwork_free() when
+ * Returns: a new #Itdb_Artwork to be freed with itdb_artwork_free() when
  * no longer needed
- **/
+ *
+ * Since: 0.3.0
+ */
 Itdb_Artwork *itdb_artwork_new (void)
 {
     Itdb_Artwork *artwork = g_new0 (Itdb_Artwork, 1);
@@ -62,7 +64,9 @@ Itdb_Artwork *itdb_artwork_new (void)
  * @artwork: an #Itdb_Artwork
  *
  * Frees memory used by @artwork
- **/
+ *
+ * Since: 0.3.0
+ */
 void itdb_artwork_free (Itdb_Artwork *artwork)
 {
     g_return_if_fail (artwork);
@@ -78,8 +82,10 @@ void itdb_artwork_free (Itdb_Artwork *artwork)
  *
  * Duplicates @artwork
  *
- * Return value: a new copy of @artwork
- **/
+ * Returns: a new copy of @artwork
+ *
+ * Since: 0.3.0
+ */
 Itdb_Artwork *itdb_artwork_duplicate (Itdb_Artwork *artwork)
 {
     Itdb_Artwork *dup;
@@ -101,7 +107,9 @@ Itdb_Artwork *itdb_artwork_duplicate (Itdb_Artwork *artwork)
  * @artwork: an #Itdb_Artwork
  *
  * Removes all thumbnails from @artwork
- **/
+ *
+ * Since: 0.3.0
+ */
 void
 itdb_artwork_remove_thumbnails (Itdb_Artwork *artwork)
 {
@@ -117,24 +125,25 @@ itdb_artwork_remove_thumbnails (Itdb_Artwork *artwork)
 
 /**
  * itdb_artwork_set_thumbnail
- * @artwork: an #Itdb_Thumbnail
- * @type: thumbnail size
- * @filename: image file to use to create the thumbnail
- * @rotation: angle by which the image should be rotated
- * counterclockwise. Valid values are 0, 90, 180 and 270.
- * @error: return location for a #GError or NULL
+ * @artwork:    an #Itdb_Artwork
+ * @filename:   image file to use to create the thumbnail
+ * @rotation:   angle by which the image should be rotated
+ *              counterclockwise. Valid values are 0, 90, 180 and 270.
+ * @error:      return location for a #GError or NULL
  *
  * Appends a thumbnail of type @type to existing thumbnails in @artwork. No
  * data is read from @filename yet, the file will be when @artwork is saved to
  * disk. @filename must still exist when that happens.
  *
  * For the rotation angle you can also use the gdk constants
- * GDK_PIXBUF_ROTATE_NONE, ..._COUNTERCLOCKWISE, ..._UPSIDEDOWN AND
- * ..._CLOCKWISE.
+ * %GDK_PIXBUF_ROTATE_NONE, %GDK_PIXBUF_ROTATE_COUNTERCLOCKWISE,
+ * %GDK_PIXBUF_ROTATE_UPSIDEDOWN, AND %GDK_PIXBUF_ROTATE_CLOCKWISE.
  *
- * Return value: TRUE if the thumbnail could be successfully added, FALSE
+ * Returns: TRUE if the thumbnail could be successfully added, FALSE
  * otherwise. @error is set appropriately.
- **/
+ *
+ * Since: 0.7.0
+ */
 gboolean
 itdb_artwork_set_thumbnail (Itdb_Artwork *artwork,
 			    const gchar *filename,
@@ -176,24 +185,25 @@ itdb_artwork_set_thumbnail (Itdb_Artwork *artwork,
 
 /**
  * itdb_artwork_set_thumbnail_from_pixbuf
- * @artwork: an #Itdb_Thumbnail
- * @pixbuf: #GdkPixbuf to use to create the thumbnail
- * @rotation: angle by which the image should be rotated
- * counterclockwise. Valid values are 0, 90, 180 and 270.
- * @error: return location for a #GError or NULL
+ * @artwork:    an #Itdb_Artwork
+ * @pixbuf:     #GdkPixbuf to use to create the thumbnail
+ * @rotation:   angle by which the image should be rotated
+ *              counterclockwise. Valid values are 0, 90, 180 and 270.
+ * @error:      return location for a #GError or NULL
  *
- * Appends a thumbnail of type @type to existing thumbnails in @artwork. No 
- * data is generated from @pixbuf yet, it will be done when @artwork is saved 
- * to disk. @pixbuf is ref'ed by this function, but is not copied, so it should
- * not be modified before the database is saved.
+ * Set a thumbnail in @artwork. No data is generated from @pixbuf yet, it will
+ * be done when @artwork is saved to disk. @pixbuf is ref'ed by this function,
+ * but is not copied, so it should not be modified before the database is saved.
  *
  * For the rotation angle you can also use the gdk constants
- * GDK_PIXBUF_ROTATE_NONE, ..._COUNTERCLOCKWISE, ..._UPSIDEDOWN AND
- * ..._CLOCKWISE.
+ * %GDK_PIXBUF_ROTATE_NONE, %GDK_PIXBUF_ROTATE_COUNTERCLOCKWISE,
+ * %GDK_PIXBUF_ROTATE_UPSIDEDOWN, AND %GDK_PIXBUF_ROTATE_CLOCKWISE.
  *
- * Return value: TRUE if the thumbnail could be successfully added, FALSE
+ * Returns: TRUE if the thumbnail could be successfully added, FALSE
  * otherwise. @error is set appropriately.
- **/
+ *
+ * Since: 0.7.0
+ */
 gboolean
 itdb_artwork_set_thumbnail_from_pixbuf (Itdb_Artwork *artwork,
                                         gpointer pixbuf,
@@ -235,25 +245,26 @@ itdb_artwork_set_thumbnail_from_pixbuf (Itdb_Artwork *artwork,
 
 /**
  * itdb_artwork_set_thumbnail_from_data
- * @artwork: an #Itdb_Thumbnail
- * @image_data: data used to create the thumbnail (the raw contents of
- *              an image file)
+ * @artwork:        an #Itdb_Artwork
+ * @image_data:     data used to create the thumbnail (the raw contents of
+ *                  an image file)
  * @image_data_len: length of above data block
- * @rotation: angle by which the image should be rotated
- * counterclockwise. Valid values are 0, 90, 180 and 270.
- * @error: return location for a #GError or NULL
+ * @rotation:       angle by which the image should be rotated
+ *                  counterclockwise. Valid values are 0, 90, 180 and 270.
+ * @error:          return location for a #GError or NULL
  *
- * Appends a thumbnail of type @type to existing thumbnails in
- * @artwork. No data is processed yet. This will be done when @artwork
- * is saved to disk.
+ * Set a thumbnail in @artwork. No data is processed yet. This will be done when
+ * @artwork is saved to disk.
  *
  * For the rotation angle you can also use the gdk constants
- * GDK_PIXBUF_ROTATE_NONE, ..._COUNTERCLOCKWISE, ..._UPSIDEDOWN AND
- * ..._CLOCKWISE.
+ * %GDK_PIXBUF_ROTATE_NONE, %GDK_PIXBUF_ROTATE_COUNTERCLOCKWISE,
+ * %GDK_PIXBUF_ROTATE_UPSIDEDOWN, AND %GDK_PIXBUF_ROTATE_CLOCKWISE.
  *
- * Return value: TRUE if the thumbnail could be successfully added, FALSE
+ * Returns: TRUE if the thumbnail could be successfully added, FALSE
  * otherwise. @error is set appropriately.
- **/
+ *
+ * Since: 0.7.0
+ */
 gboolean
 itdb_artwork_set_thumbnail_from_data (Itdb_Artwork *artwork,
 				      const guchar *image_data,
@@ -881,23 +892,25 @@ gpointer itdb_thumb_ipod_item_to_pixbuf (Itdb_Device *device,
 #endif
 
 /**
- * itdb_artwork_get_thumbnail!
- * @artwork: an #Itdb_Artwork
- *
- * @width: width of the pixbuf to retrieve, -1 for the biggest
- * possible size and 0 for the smallest possible size (with no scaling)
- *
- * @height: height of the pixbuf to retrieve, -1 for the biggest possible size
- * and 0 for the smallest possible size (with no scaling)
+ * itdb_artwork_get_pixbuf:
+ * @artwork:    an #Itdb_Artwork
+ * @device:     an #Itdb_Device
+ * @width:      width of the pixbuf to retrieve, -1 for the biggest
+ *              possible size and 0 for the smallest possible size (with no
+ *              scaling)
+ * @height:     height of the pixbuf to retrieve, -1 for the biggest possible
+ *              size and 0 for the smallest possible size (with no scaling)
  *
  * Returns a #GdkPixbuf representing the thumbnail stored in @artwork
  * scaling it if appropriate. If either height or width is -1, then the
  * biggest unscaled thumbnail available will be returned
  *
- * Return value: a #GdkPixbuf that must be unreffed when no longer used, NULL
+ * Returns: a #GdkPixbuf that must be unreffed when no longer used, NULL
  * if no artwork could be found or if libgpod is compiled without GdkPixbuf
  * support
- **/
+ *
+ * Since: 0.7.0
+ */
 gpointer itdb_artwork_get_pixbuf (Itdb_Device *device, Itdb_Artwork *artwork,
                                   gint width, gint height)
 {
diff --git a/src/itdb_chapterdata.c b/src/itdb_chapterdata.c
index 131f66e..c74e6d6 100644
--- a/src/itdb_chapterdata.c
+++ b/src/itdb_chapterdata.c
@@ -41,9 +41,11 @@
  *
  * Creates a new #Itdb_Chapterdata
  *
- * Return value: a new #Itdb_Chapterdata to be freed with itdb_chapterdata_free() when
- * no longer needed
- **/
+ * Returns: a new #Itdb_Chapterdata to be freed with
+ *               itdb_chapterdata_free() when no longer needed
+ *
+ * Since: 0.7.0
+ */
 Itdb_Chapterdata *itdb_chapterdata_new (void)
 {
     Itdb_Chapterdata *chapterdata = g_new0 (Itdb_Chapterdata, 1);
@@ -55,7 +57,9 @@ Itdb_Chapterdata *itdb_chapterdata_new (void)
  * @chapterdata: an #Itdb_Chapterdata
  *
  * Frees memory used by @chapterdata
- **/
+ *
+ * Since: 0.7.0
+ */
 void itdb_chapterdata_free (Itdb_Chapterdata *chapterdata)
 {
     g_return_if_fail (chapterdata);
@@ -92,8 +96,10 @@ static GList *dup_chapters (GList *chapters)
  *
  * Duplicates @chapterdata
  *
- * Return value: a new copy of @chapterdata
- **/
+ * Returns: a new copy of @chapterdata
+ *
+ * Since: 0.7.0
+ */
 Itdb_Chapterdata *itdb_chapterdata_duplicate (Itdb_Chapterdata *chapterdata)
 {
     Itdb_Chapterdata *dup;
@@ -116,10 +122,12 @@ Itdb_Chapterdata *itdb_chapterdata_duplicate (Itdb_Chapterdata *chapterdata)
 /**
  * itdb_chapterdata_remove_chapter:
  * @chapterdata: an #Itdb_Chapterdata
- * @chapeer: an #Itdb_Chapter
+ * @chapter:     an #Itdb_Chapter
  *
  * Removes @chapter from @chapterdata. The memory used by @chapter is freed.
- **/
+ *
+ * Since: 0.7.0
+ */
 void
 itdb_chapterdata_remove_chapter (Itdb_Chapterdata *chapterdata, Itdb_Chapter *chapter)
 {
@@ -135,7 +143,9 @@ itdb_chapterdata_remove_chapter (Itdb_Chapterdata *chapterdata, Itdb_Chapter *ch
  * @chapterdata: an #Itdb_Chapterdata
  *
  * Removes all chapters from @chapterdata
- **/
+ *
+ * Since: 0.7.0
+ */
 void
 itdb_chapterdata_remove_chapters (Itdb_Chapterdata *chapterdata)
 {
@@ -154,9 +164,11 @@ itdb_chapterdata_remove_chapters (Itdb_Chapterdata *chapterdata)
  *
  * Creates a new #Itdb_Chapter
  *
- * Return Value: newly allocated #Itdb_Chapter to be freed with itdb_chapter_free()
+ * Returns: newly allocated #Itdb_Chapter to be freed with itdb_chapter_free()
  * after use
- **/
+ *
+ * Since: 0.7.0
+ */
 Itdb_Chapter *itdb_chapter_new (void)
 {
     Itdb_Chapter *chapter = g_new0 (Itdb_Chapter, 1);
@@ -168,7 +180,9 @@ Itdb_Chapter *itdb_chapter_new (void)
  * @chapter: an #Itdb_Chapter
  *
  * Frees the memory used by @chapter
- **/
+ *
+ * Since: 0.7.0
+ */
 void itdb_chapter_free (Itdb_Chapter *chapter)
 {
     g_return_if_fail (chapter);
@@ -183,9 +197,11 @@ void itdb_chapter_free (Itdb_Chapter *chapter)
  *
  * Duplicates the data contained in @chapter
  *
- * Return value: a newly allocated copy of @chapter to be freed with
+ * Returns: a newly allocated copy of @chapter to be freed with
  * itdb_chapter_free() after use
- **/
+ *
+ * Since: 0.7.0
+ */
 Itdb_Chapter *itdb_chapter_duplicate (Itdb_Chapter *chapter)
 {
     Itdb_Chapter *new_chapter;
@@ -201,15 +217,17 @@ Itdb_Chapter *itdb_chapter_duplicate (Itdb_Chapter *chapter)
 
 /**
  * itdb_chapterdata_add_chapter
- * @chapterdata: an #Itdb_Chapterdata
- * @startpos: chapter start time in milliseconds
+ * @chapterdata:  an #Itdb_Chapterdata
+ * @startpos:     chapter start time in milliseconds
  * @chaptertitle: chapter title
  *
  * Appends a chapter to existing chapters in @chapterdata.
  *
- * Return value: TRUE if the chapter could be successfully added, FALSE
+ * Returns: TRUE if the chapter could be successfully added, FALSE
  * otherwise.
- **/
+ *
+ * Since: 0.7.0
+ */
 gboolean
 itdb_chapterdata_add_chapter (Itdb_Chapterdata *chapterdata,
 			      gint32 startpos,
diff --git a/src/itdb_device.c b/src/itdb_device.c
index 6261711..b035c30 100644
--- a/src/itdb_device.c
+++ b/src/itdb_device.c
@@ -649,9 +649,11 @@ static void itdb_device_reset_sysinfo (Itdb_Device *device)
  * 
  * Creates a new #Itdb_Device structure
  *
- * Return value: a newly allocated #Itdb_Device which must be freed with
+ * Returns: a newly allocated #Itdb_Device which must be freed with
  * itdb_device_free() when no longer needed
- **/
+ *
+ * Since: 0.4.0
+ */
 Itdb_Device *itdb_device_new ()
 {
     Itdb_Device *dev;
@@ -666,7 +668,9 @@ Itdb_Device *itdb_device_new ()
  * @device: an #Itdb_Device
  *
  * Frees memory used by @device
- **/
+ *
+ * Since: 0.4.0
+ */
 void itdb_device_free (Itdb_Device *device)
 {
     if (device)
@@ -684,11 +688,13 @@ void itdb_device_free (Itdb_Device *device)
 /**
  * itdb_device_set_mountpoint:
  * @device: an #Itdb_Device
- * @mp: the new mount point
+ * @mp:     the new mount point
  *
  * Sets the mountpoint of @device to @mp and update the cached device 
  * information (in particular, re-read the SysInfo file)
- **/
+ *
+ * Since: 0.4.0
+ */
 void itdb_device_set_mountpoint (Itdb_Device *device, const gchar *mp)
 {
     g_return_if_fail (device);
@@ -753,8 +759,10 @@ static void itdb_device_read_sysinfo_extended (Itdb_Device *device)
  * Reads the SysInfo file and stores information in device->sysinfo for
  * later use.
  *
- * Return value: TRUE if file could be read, FALSE otherwise 
- **/
+ * Returns: TRUE if file could be read, FALSE otherwise 
+ *
+ * Since: 0.4.0
+ */
 gboolean itdb_device_read_sysinfo (Itdb_Device *device)
 {
     const gchar *p_sysinfo[] = {"SysInfo", NULL};
@@ -827,13 +835,15 @@ static void write_sysinfo_entry (const gchar *key,
 /** 
  * itdb_device_write_sysinfo:
  * @device: an #Itdb_Device
- * @error: return location for a #GError or NULL
+ * @error:  return location for a #GError or NULL
  *
  * Fills the SysInfo file with information in device->sysinfo. Note:
  * no directories are created if not already existent.
  *
- * Return value: TRUE if file could be read, FALSE otherwise 
- **/
+ * Returns: TRUE if file could be read, FALSE otherwise 
+ *
+ * Since: 0.4.0
+ */
 gboolean itdb_device_write_sysinfo (Itdb_Device *device, GError **error)
 {
     gchar *devicedir;
@@ -883,13 +893,15 @@ gboolean itdb_device_write_sysinfo (Itdb_Device *device, GError **error)
 /**
  * itdb_device_get_sysinfo:
  * @device: an #Itdb_Device
- * @field: field to retrive information from
+ * @field:  field to retrive information from
  *
  * Retrieve specified field from the SysInfo file.
  *
- * Return value: the information associated with @field, or NULL if @field
+ * Returns: the information associated with @field, or NULL if @field
  * couldn't be found. g_free() after use
- **/
+ *
+ * Since: 0.4.0
+ */
 gchar *itdb_device_get_sysinfo (const Itdb_Device *device, const gchar *field)
 {
     g_return_val_if_fail (device, NULL);
@@ -902,13 +914,14 @@ gchar *itdb_device_get_sysinfo (const Itdb_Device *device, const gchar *field)
 /**
  * itdb_device_set_sysinfo:
  * @device: an #Itdb_Device
- * @field: field to set
- * @value: value to set (or NULL to remove the field).
+ * @field:  field to set
+ * @value:  value to set (or NULL to remove the field).
  *
  * Set specified field. It can later be written to the iPod using
  * itdb_device_write_sysinfo()
  *
- **/
+ * Since: 0.4.0
+ */
 void itdb_device_set_sysinfo (Itdb_Device *device,
 			      const gchar *field, const gchar *value)
 {
@@ -935,8 +948,10 @@ void itdb_device_set_sysinfo (Itdb_Device *device,
  *
  * Retrieve the #Itdb_IpodInfo entry for this iPod
  *
- * Return value: the #Itdb_IpodInfo entry for this iPod
- **/
+ * Returns: the #Itdb_IpodInfo entry for this iPod
+ *
+ * Since: 0.4.0
+ */
 const Itdb_IpodInfo *
 itdb_device_get_ipod_info (const Itdb_Device *device)
 {
@@ -1154,16 +1169,14 @@ itdb_device_musicdirs_number (Itdb_Device *device)
     return device->musicdirs;
 }
 
-/**
+/*
  * endianess_check_path:
+ * @path:   the file to look at.
+ * @hdr:    the header string (4 bytes) in case of LITTLE_ENDIAN
  *
  * Check if endianess can be determined by looking at header of @path.
  *
- * @path:   the file to look at.
- * @hdr: the header string (4 bytes) in case of LITTLE_ENDIAN
- *
- * Return value:
- * G_LITTLE_ENDIAN, G_BIG_ENDIAN or 0 if endianess could not be
+ * Returns: G_LITTLE_ENDIAN, G_BIG_ENDIAN or 0 if endianess could not be
  * determined.
  */
 static guint endianess_check_path (const gchar *path, const gchar *hdr)
@@ -1273,8 +1286,10 @@ itdb_device_autodetect_endianess (Itdb_Device *device)
  * Return a pointer to the start of valid iPod model descriptions,
  * which is an array of #Itdb_IpodInfo entries.
  *
- * Return value: a pointer to the array of #Itdb_IpodInfo entries.
- **/
+ * Returns: a pointer to the array of #Itdb_IpodInfo entries.
+ *
+ * Since: 0.4.0
+ */
 const Itdb_IpodInfo *itdb_info_get_ipod_info_table (void)
 {
     return &ipod_info_table[2];
@@ -1287,9 +1302,11 @@ const Itdb_IpodInfo *itdb_info_get_ipod_info_table (void)
  *
  * Return the iPod's generic model name, like "Color", "Nano"...
  *
- * Return value: a pointer to the model name. This is a static string
+ * Returns: a pointer to the model name. This is a static string
  * and must not be g_free()d.
- **/
+ *
+ * Since: 0.4.0
+ */
 const gchar *itdb_info_get_ipod_model_name_string (Itdb_IpodModel model)
 {
     gint i=0;
@@ -1312,9 +1329,11 @@ const gchar *itdb_info_get_ipod_model_name_string (Itdb_IpodModel model)
  * Return the iPod's generic generation name, like "First Generation",
  * "Mobile Phone"...
  *
- * Return value: a pointer to the generation name. This is a static
+ * Returns: a pointer to the generation name. This is a static
  * string and must not be g_free()d.
- **/
+ *
+ * Since: 0.4.0
+ */
 const gchar *itdb_info_get_ipod_generation_string (Itdb_IpodGeneration generation)
 {
     gint i=0;
@@ -1339,7 +1358,9 @@ const gchar *itdb_info_get_ipod_generation_string (Itdb_IpodGeneration generatio
  * with a non-art capable iPod, no artwork data will be written to the
  * iPod so you can spare calls to the artwork handling methods.
  *
- * Return value: true if @device can display artwork.
+ * Returns: true if @device can display artwork.
+ *
+ * Since: 0.5.0
  */
 gboolean itdb_device_supports_artwork (const Itdb_Device *device)
 {
@@ -1359,7 +1380,9 @@ gboolean itdb_device_supports_artwork (const Itdb_Device *device)
  *
  * Indicates whether @device can play videos or not.
  *
- * Return value: true if @device can play videos.
+ * Returns: true if @device can play videos.
+ *
+ * Since: 0.7.0
  */
 gboolean itdb_device_supports_video (const Itdb_Device *device)
 {
@@ -1405,7 +1428,9 @@ gboolean itdb_device_supports_video (const Itdb_Device *device)
  *
  * Indicates whether @device can display photos or not.
  *
- * Return value: true if @device can display photos.
+ * Returns: true if @device can display photos.
+ *
+ * Since: 0.5.0
  */
 gboolean itdb_device_supports_photo (const Itdb_Device *device)
 {
@@ -1597,8 +1622,10 @@ static void itdb_device_set_timezone_info (Itdb_Device *device)
  * iTunesDB checksum which is expected by newer iPod models
  * (iPod classic/fat nanos)
  *
- * Return value: the guint64 firewire id, or 0 if we don't know it
- **/
+ * Returns: the guint64 firewire id, or 0 if we don't know it
+ *
+ * Since: 0.6.0
+ */
 guint64 itdb_device_get_firewire_id (const Itdb_Device *device)
 {
     gchar *fwid;
@@ -1664,14 +1691,14 @@ G_GNUC_INTERNAL gboolean itdb_device_requires_checksum (Itdb_Device *device)
 /**
  * itdb_device_get_storage_info:
  *
- * @device: an #Itdb_Device
+ * @device:   an #Itdb_Device
  * @capacity: returned capacity in bytes
- * @free: returned free space in bytes
+ * @free:     returned free space in bytes
  *
  * Return the storage info for this iPod
  *
- * Return value: TRUE if storage info could be obtained, FALSE otherwise
- **/
+ * Returns: TRUE if storage info could be obtained, FALSE otherwise
+ */
 gboolean itdb_device_get_storage_info (Itdb_Device *device, guint64 *capacity, guint64 *free)
 {
 #ifdef WIN32
diff --git a/src/itdb_device.h b/src/itdb_device.h
index 1888a27..7a37177 100644
--- a/src/itdb_device.h
+++ b/src/itdb_device.h
@@ -74,33 +74,68 @@ 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
+ *
+ * Since: 0.4.0
+ */
 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;
 };
 
+/**
+ * Itdb_ArtworkFormat:
+ * @format_id:          Unique ID for the format (generally a 4 digit int)
+ * @width:              Width of the thumbnail
+ * @height:             Height of the thumbnail
+ * @format:             Pixel format of the thumbnail (RGB, YUV, ...)
+ * @padding:            Number of bytes of padding to add after the thumbnail
+ *                      (not found in SysInfoExtended -- added for
+ *                      compatibility with hardcoded artwork formats)
+ * @crop:               Indicates if the thumbnail is to be cropped
+ * @rotation:           Degrees to rotate the thumbnail
+ * @back_color:         Background color for the thumbnail
+ * @display_width:      Width at which the thumbnail will be displayed
+ *                      (not currently used)
+ * @interlaced:         If TRUE, the thumbnails are interlaced
+ *                      (not currently used)
+ * @align_row_bytes:    If TRUE, each pixel row must be aligned a 2-byte boundary
+ * @color_adjustment:   Color adjustment for the thumbnails
+ *                      (not currently used)
+ * @gamma:              Gamma value for the thumbails
+ *                      (not currently used)
+ * @associated_format:  Unknown (not currently used)
+ *
+ * Structure representing the characteristics of the thumbnails to
+ * write to a given .ithmb file. The format of the structure is based
+ * on the way artwork formats are written to SysInfoExtended.
+ */
 struct _Itdb_ArtworkFormat {
         gint format_id;
         gint width;
         gint height;
         ItdbThumbFormat format;
-        gint32 padding; /* not found in SysInfoExtended, added
-                         * for compatibility with hardcoded artwork formats */
+        gint32 padding;
         gboolean crop;
         gint rotation;
         guchar back_color[4];
diff --git a/src/itdb_itunesdb.c b/src/itdb_itunesdb.c
index 8cdffc6..f30ac0f 100644
--- a/src/itdb_itunesdb.c
+++ b/src/itdb_itunesdb.c
@@ -354,13 +354,13 @@ static void fcontents_free (FContents *cts)
  * Resolve the path to a track on the iPod
  *
  * We start by assuming that the iPod mount point exists.  Then, for
- * each component c of track-&gt;ipod_path, we try to find an entry d in
+ * each component c of @track->ipod_path, we try to find an entry d in
  * good_path that is case-insensitively equal to c.  If we find d, we
  * append d to good_path and make the result the new good_path.
  * Otherwise, we quit and return NULL.
  *
- * Return value: path to track on the iPod or NULL.
- **/
+ * Returns: path to track on the iPod or NULL.
+ */
 gchar * itdb_resolve_path (const gchar *root,
 			   const gchar * const * components)
 {
@@ -1147,7 +1147,7 @@ static void itdb_free_fimp (FImport *fimp)
  * @itdb: an #Itdb_iTunesDB
  *
  * Free the memory taken by @itdb. 
- **/
+ */
 void itdb_free (Itdb_iTunesDB *itdb)
 {
     if (itdb)
@@ -1173,8 +1173,8 @@ void itdb_free (Itdb_iTunesDB *itdb)
  * Duplicate @itdb 
  * FIXME: not implemented yet 
  *
- * Return value: always return NULL since it's unimplemented
- **/
+ * Returns: always return NULL since it's unimplemented
+ */
 Itdb_iTunesDB *itdb_duplicate (Itdb_iTunesDB *itdb)
 {
     g_return_val_if_fail (itdb, NULL);
@@ -1188,9 +1188,9 @@ Itdb_iTunesDB *itdb_duplicate (Itdb_iTunesDB *itdb)
  *
  * Counts the number of playlists stored in @itdb
  *
- * Return value: the number of playlists in @itdb (including the master 
+ * Returns: the number of playlists in @itdb (including the master 
  * playlist)
- **/
+ */
 guint32 itdb_playlists_number (Itdb_iTunesDB *itdb)
 {
     g_return_val_if_fail (itdb, 0);
@@ -1204,8 +1204,8 @@ guint32 itdb_playlists_number (Itdb_iTunesDB *itdb)
  *
  * Counts the number of tracks stored in @itdb
  *
- * Return value: the number of tracks in @itdb
- **/
+ * Returns: the number of tracks in @itdb
+ */
 guint32 itdb_tracks_number (Itdb_iTunesDB *itdb)
 {
     g_return_val_if_fail (itdb, 0);
@@ -1219,10 +1219,10 @@ guint32 itdb_tracks_number (Itdb_iTunesDB *itdb)
  *
  * Counts the number of non-transferred tracks in @itdb
  *
- * Return value: the number of tracks in @itdb that haven't been transferred
+ * Returns: the number of tracks in @itdb that haven't been transferred
  * to the iPod yet (ie the number of #Itdb_Track in which the transferred field
  * is false)
- **/
+ */
 guint32 itdb_tracks_number_nontransferred (Itdb_iTunesDB *itdb)
 {
     guint n = 0;
@@ -1244,9 +1244,9 @@ guint32 itdb_tracks_number_nontransferred (Itdb_iTunesDB *itdb)
  * Creates a new Itdb_iTunesDB with the unknowns filled in to reasonable
  * values.
  *
- * Return value: a newly created Itdb_iTunesDB to be freed with itdb_free()
+ * Returns: a newly created Itdb_iTunesDB to be freed with itdb_free()
  * when it's no longer needed
- **/
+ */
 Itdb_iTunesDB *itdb_new (void)
 {
     static GOnce g_type_init_once = G_ONCE_INIT;
@@ -2956,16 +2956,16 @@ itdb_parse_internal (Itdb_iTunesDB *itdb, GError **error)
 
 /**
  * itdb_parse:
- * @mp: mount point of the iPod (eg "/mnt/ipod) in local encoding
- * @error: return location for a #GError or NULL
+ * @mp:     mount point of the iPod (eg "/mnt/ipod") in local encoding
+ * @error:  return location for a #GError or NULL
  *
  * Parse the Itdb_iTunesDB of the iPod located at @mp
  *
- * Return value: a newly allocated #Itdb_iTunesDB struct holding the tracks and
+ * Returns: a newly allocated #Itdb_iTunesDB struct holding the tracks and
  * the playlists present on the iPod at @mp, NULL if @mp isn't an iPod mount
  * point. If non-NULL, the #Itdb_iTunesDB is to be freed with itdb_free() when
  * it's no longer needed
- **/
+ */
 Itdb_iTunesDB *itdb_parse (const gchar *mp, GError **error)
 {
     gchar *filename;
@@ -3043,16 +3043,16 @@ Itdb_iTunesDB *itdb_parse (const gchar *mp, GError **error)
 
 /**
  * itdb_parse_file:
- * @filename: path to a file in iTunesDB format
- * @error: return location for a #GError or NULL
+ * @filename:   path to a file in iTunesDB format
+ * @error:      return location for a #GError or NULL
  *
  *  Same as itunesdb_parse(), but filename is specified directly.
  *
- * Return value: a newly allocated #Itdb_iTunesDB struct holding the tracks and
+ * Returns: a newly allocated #Itdb_iTunesDB struct holding the tracks and
  * the playlists present in @filename, NULL if @filename isn't a parsable 
  * iTunesDB file. If non-NULL, the #Itdb_iTunesDB is to be freed with 
  * itdb_free() when it's no longer needed
- **/
+ */
 Itdb_iTunesDB *itdb_parse_file (const gchar *filename, GError **error)
 {
     Itdb_iTunesDB *itdb;
@@ -5116,15 +5116,15 @@ static gboolean write_db_checksum (FExport *fexp, GError **error)
 
 /**
  * itdb_write_file:
- * @itdb: the #Itdb_iTunesDB to save
- * @filename: filename to save @itdb to
- * @error: return location for a #GError or NULL
+ * @itdb:       the #Itdb_iTunesDB to save
+ * @filename:   filename to save @itdb to
+ * @error:      return location for a #GError or NULL
  *
  * Write the content of @itdb to @filename. If @filename is NULL, it attempts
- * to write to itdb-&gt;filename.
+ * to write to @itdb->filename.
  *
- * Return value: TRUE if all went well, FALSE otherwise
- **/
+ * Returns: TRUE if all went well, FALSE otherwise
+ */
 gboolean itdb_write_file (Itdb_iTunesDB *itdb, const gchar *filename,
 			  GError **error)
 {
@@ -5211,8 +5211,8 @@ gboolean itdb_write_file (Itdb_iTunesDB *itdb, const gchar *filename,
 
 /**
  * itdb_write:
- * @itdb: the #Itdb_iTunesDB to write to disk
- * @error: return location for a #GError or NULL
+ * @itdb:   the #Itdb_iTunesDB to write to disk
+ * @error:  return location for a #GError or NULL
  *
  * Write out an iTunesDB. It reassigns unique IDs to all tracks. 
  * An existing "Play Counts" file is renamed to "Play Counts.bak" if
@@ -5220,9 +5220,9 @@ gboolean itdb_write_file (Itdb_iTunesDB *itdb, const gchar *filename,
  * An existing "OTGPlaylistInfo" file is removed if the export was
  * successful.
  *
- * Return value: TRUE on success, FALSE on error, in which case @error is
+ * Returns: TRUE on success, FALSE on error, in which case @error is
  * set accordingly.
- **/
+ */
 gboolean itdb_write (Itdb_iTunesDB *itdb, GError **error)
 {
     gchar *itunes_filename, *itunes_path;
@@ -5376,21 +5376,20 @@ All integers in the iTunesSD file are in BIG endian form...
 
 /**
  * itdb_shuffle_write:
- * @itdb: the #Itdb_iTunesDB to write to disk
- * @error: return location for a #GError or NULL
+ * @itdb:   the #Itdb_iTunesDB to write to disk
+ * @error:  return location for a #GError or NULL
  *
  * Write out an iTunesSD for the Shuffle.
- * First reassigns unique IDs to all tracks.
- * An existing "Play Counts" file is renamed to "Play Counts.bak" if
- * the export was successful.
- * An existing "OTGPlaylistInfo" file is removed if the export was
- * successful.
- * @itdb->mountpoint must point to the mount point of the iPod,
- * e.g. "/mnt/ipod" and be in local encoding.
  *
- * Return value: TRUE on success, FALSE on error, in which case @error is
+ * First reassigns unique IDs to all tracks.  An existing "Play
+ * Counts" file is renamed to "Play Counts.bak" if the export was
+ * successful.  An existing "OTGPlaylistInfo" file is removed if the
+ * export was successful.  @itdb->mountpoint must point to the mount
+ * point of the iPod, e.g. "/mnt/ipod" and be in local encoding.
+ *
+ * Returns: TRUE on success, FALSE on error, in which case @error is
  * set accordingly.
- **/
+ */
 gboolean itdb_shuffle_write (Itdb_iTunesDB *itdb, GError **error)
 {
     gchar *itunes_filename, *itunes_path;
@@ -5445,15 +5444,15 @@ static gboolean haystack (gchar *filetype, gchar **desclist)
 
 /**
  * itdb_shuffle_write_file:
- * @itdb: the #Itdb_iTunesDB to write to disk
- * @filename: file to write to, cannot be NULL
- * @error: return location for a #GError or NULL
+ * @itdb:       the #Itdb_iTunesDB to write to disk
+ * @filename:   file to write to, cannot be NULL
+ * @error:      return location for a #GError or NULL
  *
  * Do the actual writing to the iTunesSD
  *
- * Return value: TRUE on success, FALSE on error, in which case @error is
+ * Returns: TRUE on success, FALSE on error, in which case @error is
  * set accordingly.
- **/
+ */
 gboolean itdb_shuffle_write_file (Itdb_iTunesDB *itdb,
 				  const gchar *filename, GError **error)
 {
@@ -5568,16 +5567,16 @@ gboolean itdb_shuffle_write_file (Itdb_iTunesDB *itdb,
 
 /**
  * itdb_rename_files:
- * @mp: mount point of the iPod
- * @error: return location for a #GError or NULL
+ * @mp:     mount point of the iPod
+ * @error:  return location for a #GError or NULL
  *
  * Renames/removes some files on the iPod (Playcounts, OTG
  * semaphore). May have to be called if you write the iTunesDB not
  * directly to the iPod but to some other location and then manually
  * copy the file from there to the iPod.
  *
- * Return value: FALSE on error and sets @error accordingly
- **/
+ * Returns: FALSE on error and sets @error accordingly
+ */
 gboolean itdb_rename_files (const gchar *mp, GError **error)
 {
     const gchar *db_plc_o[] = {"Play Counts", NULL};
@@ -5667,12 +5666,12 @@ gboolean itdb_rename_files (const gchar *mp, GError **error)
 
 /**
  * itdb_filename_fs2ipod:
- * @filename: a filename 'PC-style' (eg /iPod_Control/Music/f00/test.mp3)
+ * @filename: a 'PC-style' filename (eg /iPod_Control/Music/f00/test.mp3)
  *
- * Convert string from casual PC file name to iPod iTunesDB format using ':' 
- * instead of G_DIR_SEPARATOR_S (ie slashes on Unix-like systems). @ipod_file
- * is modified in place.
- **/
+ * Convert string from casual PC file name to iPod iTunesDB format
+ * using ':' instead of G_DIR_SEPARATOR_S (i.e. slashes on Unix-like
+ * systems). @ipod_file is modified in place.
+ */
 void itdb_filename_fs2ipod (gchar *ipod_file)
 {
     g_strdelimit (ipod_file, G_DIR_SEPARATOR_S, ':');
@@ -5680,12 +5679,12 @@ void itdb_filename_fs2ipod (gchar *ipod_file)
 
 /**
  * itdb_filename_ipod2fs:
- * @ipod_file: a filename 'PC-style' (eg /iPod_Control/Music/f00/test.mp3)
+ * @ipod_file: a 'PC-style' filename (eg /iPod_Control/Music/f00/test.mp3)
  *
- * Convert string from from iPod iTunesDB format to casual PC file name
- * using G_DIR_SEPARATOR (ie slashes on Unix-like systems) instead of ':'.
- * @ipod_file is modified in place.
- **/
+ * Convert string from from iPod iTunesDB format to casual PC file
+ * name using G_DIR_SEPARATOR (ie slashes on Unix-like systems)
+ * instead of ':'.  @ipod_file is modified in place.
+ */
 void itdb_filename_ipod2fs (gchar *ipod_file)
 {
     g_strdelimit (ipod_file, ":", G_DIR_SEPARATOR);
@@ -5693,14 +5692,16 @@ void itdb_filename_ipod2fs (gchar *ipod_file)
 
 /**
  * itdb_set_mountpoint:
- * @itdb: an #Itdb_iTunesDB
- * @mp: new mount point
+ * @itdb:   an #Itdb_iTunesDB
+ * @mp:     new mount point
  *
- * Sets the mountpoint of @db. Always use this function to set the mountpoint
- * of an #Itdb_iTunesDB as it will reset the number of available 
- * /iPod_Control/Music/F.. dirs. It doesn't attempt to parse an iPod database
- * that may be present on the iPod at @mp
- **/
+ * Sets the mountpoint of @itdb. Always use this function to set the
+ * mountpoint of an #Itdb_iTunesDB as it will reset the number of
+ * available /iPod_Control/Music/F.. dirs. It doesn't attempt to parse
+ * an iPod database that may be present on the iPod at @mp.
+ *
+ * Since: 0.1.3
+ */
 void itdb_set_mountpoint (Itdb_iTunesDB *itdb, const gchar *mp)
 {
     g_return_if_fail (itdb);
@@ -5716,9 +5717,11 @@ void itdb_set_mountpoint (Itdb_iTunesDB *itdb, const gchar *mp)
  *
  * Retrieve a reference to the mountpoint of @itdb
  *
- * Return value: the @itdb mountpoint, this string shouldn't be freed nor 
- * modified
- **/
+ * Returns: the @itdb mountpoint, this string shouldn't be freed
+ * nor modified
+ *
+ * Since: 0.4.0
+ */
 const gchar *itdb_get_mountpoint (Itdb_iTunesDB *itdb)
 {
     g_return_val_if_fail (itdb, NULL);
@@ -5740,12 +5743,14 @@ const gchar *itdb_photodb_get_mountpoint (Itdb_PhotoDB *photodb)
  *
  * Determine the number of F.. directories in iPod_Control/Music.
  *
- * If itdb->musicdirs is already set, simply return the previously
+ * If @itdb->musicdirs is already set, simply return the previously
  * determined number. Otherwise count the directories first and set
- * itdb->musicdirs. 
+ * @itdb->musicdirs.
+ *
+ * Returns: max number of directories in iPod_Control/Music
  *
- * Return value: max number of directories in iPod_Control/Music
- **/
+ * Since: 0.1.3
+ */
 gint itdb_musicdirs_number (Itdb_iTunesDB *itdb)
 {
     g_return_val_if_fail (itdb, 0);
@@ -5756,29 +5761,31 @@ gint itdb_musicdirs_number (Itdb_iTunesDB *itdb)
 
 /**
  * itdb_cp_get_dest_filename:
- * @track: track to transfer or NULL
+ * @track:      track to transfer or NULL
  * @mountpoint: mountpoint of your iPod or NULL
- * @filename: the source file
- * @error: return location for a #GError or NULL
+ * @filename:   the source file
+ * @error:      return location for a #GError or NULL
  *
- * Creates a valid filename on the iPod where to copy @filename.
+ * Creates a valid filename on the iPod where @filename can be copied.
  *
- * You must either provide @track or @mountpoint. Providing @track is
+ * You must provide either @track or @mountpoint. Providing @track is
  * not thread-safe (accesses track->itdb->device and may even write to
  * track->itdb->device). Providing @mountpoint is thread-safe but
  * slightly slower because the number of music directories is counted
  * each time the function is called.
  *
- * You can use #itdb_cp() to copy the track to the iPod or implement
+ * You can use itdb_cp() to copy the track to the iPod or implement
  * your own copy function. After the file was copied you have to call
- * #itdb_cp_finalize() to obtain relevant update information for
+ * itdb_cp_finalize() to obtain relevant update information for
  * #Itdb_Track.
  *
- * Return value: a valid filename on the iPod to where @filename can
- * be copied or NULL in case of an error. In that case @error is set
+ * Returns: a valid filename on the iPod where @filename can be
+ * copied or NULL in case of an error. In that case @error is set
  * accordingly. You must free the filename when it is no longer
  * needed.
- **/
+ *
+ * Since: 0.5.0
+ */
 gchar *itdb_cp_get_dest_filename (Itdb_Track *track,
                                   const gchar *mountpoint,
 				  const gchar *filename,
@@ -5912,30 +5919,43 @@ gchar *itdb_cp_get_dest_filename (Itdb_Track *track,
 
 /**
  * itdb_cp_finalize:
- * @track: track to update or NULL
- * @mountpoint: mountpoint of your iPod or NULL
- * @dest_filename: the name of the file on the iPod copied to
- * @error: return location for a #GError or NULL
+ * @track:          track to update or NULL
+ * @mountpoint:     mountpoint of your iPod or NULL
+ * @dest_filename:  the name of the file on the iPod copied to
+ * @error:          return location for a #GError or NULL
+ *
+ * Updates information in @track necessary for the iPod.
  *
- * Updates information in @track necessary for the iPod. You must
- * either supply @track or @mountpoint. If @track == NULL, a new track
- * structure is created that must be freed with #itdb_track_free()
- * when it is no longer needed.
+ * You must supply either @track or @mountpoint. If @track == NULL, a
+ * new track structure is created that must be freed with
+ * itdb_track_free() when it is no longer needed.
  *
- * The following fields are updated:
+ * The following @track fields are updated:
  *
- * - ipod_path
- * - filetype_marker
- * - transferred
- * - size
+ * <itemizedlist>
+ *   <listitem>
+ *       ipod_path
+ *   </listitem>
+ *   <listitem>
+ *       filetype_marker
+ *   </listitem>
+ *   <listitem>
+ *       transferred
+ *   </listitem>
+ *   <listitem>
+ *       size
+ *   </listitem>
+ * </itemizedlist>
  *
- * Return value: on success a pointer to the #Itdb_Track item passed
+ * Returns: on success a pointer to the #Itdb_Track item passed
  * or a new #Itdb_Track item if @track was NULL. In the latter case
- * you must free the memory using #itdb_track_free() when the item is
+ * you must free the memory using itdb_track_free() when the item is
  * no longer used. If an error occurs NULL is returned and @error is
  * set accordingly. Errors occur when @dest_filename cannot be
  * accessed or the mountpoint is not set.
- **/
+ *
+ * Since: 0.5.0
+ */
 Itdb_Track *itdb_cp_finalize (Itdb_Track *track,
 			      const gchar *mountpoint,
 			      const gchar *dest_filename,
@@ -6037,9 +6057,9 @@ Itdb_Track *itdb_cp_finalize (Itdb_Track *track,
 
 /**
  * itdb_cp_track_to_ipod:
- * @track: the #Itdb_Track to copy (containing @filename metadata)
- * @filename: the source file
- * @error: return location for a #GError or NULL
+ * @track:      the #Itdb_Track to copy (containing @filename metadata)
+ * @filename:   the source file
+ * @error:      return location for a #GError or NULL
  * 
  * Copy one track to the iPod. The PC filename is @filename
  * and is taken literally.
@@ -6048,24 +6068,24 @@ Itdb_Track *itdb_cp_finalize (Itdb_Track *track,
  * with itdb_set_mountpoint() (done automatically when reading an
  * iTunesDB).
  *
- * If @track-&gt;transferred is set to TRUE, nothing is done. Upon
- * successful transfer @track-&gt;transferred is set to TRUE.
+ * If @track->transferred is set to TRUE, nothing is done. Upon
+ * successful transfer @track->transferred is set to TRUE.
  *
- * For storage, the directories "f00 ... fnn" will be used randomly.
+ * For storage, the directories "F00 ... Fnn" will be used randomly.
  *
- * The filename is constructed as "libgpod"&lt;random number&gt; and copied
- * to @track-&gt;ipod_path. If this file already exists, &lt;random number&gt;
+ * The filename is constructed as "libgpod@random_number" and copied
+ * to @track->ipod_path. If this file already exists, @random_number
  * is adjusted until an unused filename is found.
  *
- * If @track-&gt;ipod_path is already set, this one will be used
+ * If @track->ipod_path is already set, this one will be used
  * instead. If a file with this name already exists, it will be
  * overwritten.
  *
- * @track-&gt;filetype_marker is set according to the filename extension
+ * @track->filetype_marker is set according to the filename extension
  *
- * Return value: TRUE on success, FALSE on error, in which case @error is
+ * Returns: TRUE on success, FALSE on error, in which case @error is
  * set accordingly.
- **/
+ */
 gboolean itdb_cp_track_to_ipod (Itdb_Track *track,
 				const gchar *filename, GError **error)
 {
@@ -6100,18 +6120,22 @@ gboolean itdb_cp_track_to_ipod (Itdb_Track *track,
  * itdb_filename_on_ipod:
  * @track: an #Itdb_Track
  *
- * Return the full iPod filename as stored in @track.
+ * Get the full iPod filename as stored in @track.
  *
- * NOTE: NULL is returned when the file does not exist.
+ * <note>
+ * NULL is returned when the file does not exist.
+ * </note>
  *
- * NOTE: this code works around a problem on some systems (see
- * itdb_resolve_path() ) and might return a filename with different
- * case than the original filename. Don't copy it back to @track
- * unless you must 
+ * <note>
+ * This code works around a problem on some systems (see
+ * itdb_resolve_path()) and might return a filename with different
+ * case than the original filename. Don't copy it back to @track if
+ * you can avoid it.
+ * </note>
  *
- * Return value: full filename to @track on the iPod or NULL if no
+ * Returns: full filename to @track on the iPod or NULL if no
  * filename is set in @track. Must be freed with g_free() after use.
- **/
+ */
 gchar *itdb_filename_on_ipod (Itdb_Track *track)
 {
     gchar *result = NULL;
@@ -6150,15 +6174,15 @@ gchar *itdb_filename_on_ipod (Itdb_Track *track)
 /* Use open instead of fopen.  fwrite is really slow on the Mac. */
 /**
  * itdb_cp:
- * @from_file: source file
- * @to_file: destination file
- * @error: return location for a #GError or NULL
+ * @from_file:  source file
+ * @to_file:    destination file
+ * @error:      return location for a #GError or NULL
  *
- * Copy file "from_file" to "to_file".
+ * Copy file @from_file to @to_file.
  *
- * Return value: TRUE on success, FALSE on error, in which case @error is
+ * Returns: TRUE on success, FALSE on error, in which case @error is
  * set accordingly.
- **/
+ */
 gboolean itdb_cp (const gchar *from_file, const gchar *to_file,
 		  GError **error)
 {
@@ -6319,9 +6343,11 @@ itdb_file_set_contents (const char *filename,
  * for standard iPods and 'iTunes/iTunes_Control' for mobile
  * applications.
  *
- * Return value: path to the control dir or NULL if non-existent. Must
+ * Returns: path to the control dir or NULL if non-existent. Must
  * g_free() after use.
- **/
+ *
+ * Since: 0.4.0
+ */
 gchar *itdb_get_control_dir (const gchar *mountpoint)
 {
     gchar *p_ipod[] = {"iPod_Control", NULL};
@@ -6345,14 +6371,14 @@ gchar *itdb_get_control_dir (const gchar *mountpoint)
 /**
  * itdb_get_dir:
  * @mountpoint: the iPod mountpoint
- * @dir: a directory
+ * @dir:        a directory
  *
  * Retrieve the directory @dir by first calling itdb_get_control_dir()
  * and then adding @dir
  *
- * Return value: path to @dir or NULL if non-existent. Must g_free()
+ * Returns: path to @dir or NULL if non-existent. Must g_free()
  * after use.
- **/
+ */
 static gchar *itdb_get_dir (const gchar *mountpoint, const gchar *dir)
 {
     gchar *control_dir;
@@ -6374,14 +6400,16 @@ static gchar *itdb_get_dir (const gchar *mountpoint, const gchar *dir)
 
 /**
  * itdb_get_path:
- * @dir: a directory
- * @file: a file
+ * @dir:    a directory
+ * @file:   a file
  *
  * Retrieve a path to the @file in @dir
  *
- * Return value: path to the @file or NULL if non-existent. Must be g_free()'d 
+ * Returns: path to the @file or NULL if non-existent. Must g_free()
  * after use.
- **/
+ *
+ * Since: 0.4.0
+ */
 gchar *itdb_get_path (const gchar *dir, const gchar *file)
 {
     const gchar *p_file[] = {NULL, NULL};
@@ -6400,9 +6428,11 @@ gchar *itdb_get_path (const gchar *dir, const gchar *file)
  * Retrieve the iTunes directory (containing the iTunesDB) by first
  * calling itdb_get_control_dir() and then adding 'iTunes'
  *
- * Return value: path to the iTunes directory or NULL if non-existent.
+ * Returns: path to the iTunes directory or NULL if non-existent.
  * Must g_free() after use.
- **/
+ *
+ * Since: 0.4.0
+ */
 gchar *itdb_get_itunes_dir (const gchar *mountpoint)
 {
     g_return_val_if_fail (mountpoint, NULL);
@@ -6417,9 +6447,9 @@ gchar *itdb_get_itunes_dir (const gchar *mountpoint)
  * Retrieve the Music directory (containing the Fnn dirs) by first
  * calling itdb_get_control_dir() and then adding 'Music'
  *
- * Return value: path to the Music directory or NULL if
+ * Returns: path to the Music directory or NULL if
  * non-existent. Must g_free() after use.
- **/
+ */
 gchar *itdb_get_music_dir (const gchar *mountpoint)
 {
     g_return_val_if_fail (mountpoint, NULL);
@@ -6434,9 +6464,11 @@ gchar *itdb_get_music_dir (const gchar *mountpoint)
  * Retrieve the Device directory (containing the SysInfo file) by
  * first calling itdb_get_control_dir() and then adding 'Device'
  *
- * Return value: path to the Device directory or NULL if
+ * Returns: path to the Device directory or NULL if
  * non-existent. Must g_free() after use.
- **/
+ *
+ * Since: 0.4.0
+ */
 gchar *itdb_get_device_dir (const gchar *mountpoint)
 {
     g_return_val_if_fail (mountpoint, NULL);
@@ -6451,9 +6483,11 @@ gchar *itdb_get_device_dir (const gchar *mountpoint)
  * Retrieve the Artwork directory (containing the ArtworDB) by
  * first calling itdb_get_control_dir() and then adding 'Artwork'
  *
- * Return value: path to the Artwork directory or NULL if
+ * Returns: path to the Artwork directory or NULL if
  * non-existent. Must g_free() after use.
- **/
+ *
+ * Since: 0.4.0
+ */
 gchar *itdb_get_artwork_dir (const gchar *mountpoint)
 {
     g_return_val_if_fail (mountpoint, NULL);
@@ -6467,9 +6501,11 @@ gchar *itdb_get_artwork_dir (const gchar *mountpoint)
  *
  * Retrieve a path to the iTunesDB
  *
- * Return value: path to the iTunesDB or NULL if non-existent. Must g_free()
+ * Returns: path to the iTunesDB or NULL if non-existent. Must g_free()
  * after use.
- **/
+ *
+ * Since: 0.4.0
+ */
 gchar *itdb_get_itunesdb_path (const gchar *mountpoint)
 {
     gchar *itunes_dir, *path=NULL;
@@ -6493,9 +6529,11 @@ gchar *itdb_get_itunesdb_path (const gchar *mountpoint)
  *
  * Retrieve a path to the iTunesSD
  *
- * Return value: path to the iTunesSD or NULL if non-existent. Must g_free()
+ * Returns: path to the iTunesSD or NULL if non-existent. Must g_free()
  * after use.
- **/
+ *
+ * Since: 0.4.0
+ */
 gchar *itdb_get_itunessd_path (const gchar *mountpoint)
 {
     gchar *itunes_dir, *path=NULL;
@@ -6519,9 +6557,11 @@ gchar *itdb_get_itunessd_path (const gchar *mountpoint)
  *
  * Retrieve a path to the ArtworkDB
  *
- * Return value: path to the ArtworkDB or NULL if non-existent. Must g_free()
+ * Returns: path to the ArtworkDB or NULL if non-existent. Must g_free()
  * after use.
- **/
+ *
+ * Since: 0.4.0
+ */
 gchar *itdb_get_artworkdb_path (const gchar *mountpoint)
 {
     gchar *itunes_dir, *path=NULL;
@@ -6552,11 +6592,11 @@ gchar *itdb_get_artworkdb_path (const gchar *mountpoint)
  * Gets the current time in a format appropriate for storing in the libgpod
  * data structures
  *
- * Return value: current time
+ * Returns: current time
  *
  * Deprecated: kept for compatibility with older code, directly use
  * g_get_current_time() or time(NULL) instead
- **/
+ */
 time_t itdb_time_get_mac_time (void)
 {
     GTimeVal time;
@@ -6572,11 +6612,11 @@ time_t itdb_time_get_mac_time (void)
  *
  * Converts a timestamp from libgpod format to host system timestamp.
  *
- * Return value: timestamp for the host system
+ * Returns: timestamp for the host system
  *
  * Deprecated: It's been kept for compatibility with older code, but this
  * function is now a no-op
- **/
+ */
 time_t itdb_time_mac_to_host (time_t time)
 {
     return time;
@@ -6588,11 +6628,11 @@ time_t itdb_time_mac_to_host (time_t time)
  *
  * Convert host system timestamp to libgpod format timestamp
  *
- * Return value: a libgpod timestamp
+ * Returns: a libgpod timestamp
  *
  * Deprecated: It's been kept for compatibility with older code, but this
  * function is now a no-op
- **/
+ */
 time_t itdb_time_host_to_mac (time_t time)
 {
     return time;
@@ -6611,9 +6651,10 @@ time_t itdb_time_host_to_mac (time_t time)
  * information as well as the directory structure required for the
  * type of iPod.
  * 
- * Return value: TRUE when successful, FALSE if a failure has occurred.
- * 
- **/
+ * Returns: TRUE when successful, FALSE if a failure has occurred.
+ *
+ * Since: 0.4.0
+ */
 gboolean itdb_init_ipod (const gchar *mountpoint,
 			 const gchar *model_number,
 			 const gchar *ipod_name,
diff --git a/src/itdb_photoalbum.c b/src/itdb_photoalbum.c
index 2e6168b..84febf7 100644
--- a/src/itdb_photoalbum.c
+++ b/src/itdb_photoalbum.c
@@ -121,8 +121,10 @@ static void error_no_photos_dir (const gchar *mp, GError **error)
  * Retrieve the Photo directory by
  * first calling itdb_get_control_dir() and then adding 'Photos'
  *
- * Return value: path to the Artwork directory or NULL if
+ * Returns: path to the Artwork directory or NULL if
  * non-existent. Must g_free() after use.
+ *
+ * Since: 0.4.0
  */
 gchar *itdb_get_photos_dir (const gchar *mountpoint)
 {
@@ -149,9 +151,11 @@ gchar *itdb_get_photos_dir (const gchar *mountpoint)
  *
  * Retrieve a path to the Photo DB
  *
- * Return value: path to the PhotoDB or NULL if non-existent. Must
+ * Returns: path to the PhotoDB or NULL if non-existent. Must
  * g_free() after use.
- **/
+ *
+ * Since: 0.4.0
+ */
 gchar *itdb_get_photodb_path (const gchar *mountpoint)
 {
     gchar *photo_dir, *path=NULL;
@@ -176,8 +180,10 @@ gchar *itdb_get_photodb_path (const gchar *mountpoint)
  * Retrieve the Photo Thumbnail directory by
  * first calling itdb_get_control_dir() and then adding 'Photos/Thumbs'
  *
- * Return value: path to the Artwork directory or NULL if
+ * Returns: path to the Artwork directory or NULL if
  * non-existent. Must g_free() after use.
+ *
+ * Since: 0.4.0
  */
 gchar *itdb_get_photos_thumb_dir (const gchar *mountpoint)
 {
@@ -201,13 +207,15 @@ gchar *itdb_get_photos_thumb_dir (const gchar *mountpoint)
 
 /**
  * itdb_photodb_parse:
- * @mp: mountpoint of the iPod
- * @error: will contain the error description when an error occured.
+ * @mp:     mountpoint of the iPod
+ * @error:  will contain the error description when an error occured.
  *
  * Parses the photo database of an iPod mounted at @mp.
  *
- * Return value: the imported PhotoDB or NULL in case of an error.
- **/
+ * Returns: the imported PhotoDB or NULL in case of an error.
+ *
+ * Since: 0.4.0
+ */
 Itdb_PhotoDB *itdb_photodb_parse (const gchar *mp, GError **error)
 {
     gchar *photos_dir;
@@ -244,10 +252,12 @@ Itdb_PhotoDB *itdb_photodb_parse (const gchar *mp, GError **error)
  * Creates a new Itdb_PhotoDB. If mountpoint is NULL, you will have to
  * set it manually later by calling itdb_device_set_mountpoint().
  *
- * Return value: a newly created Itdb_PhotoDB to be freed with
+ * Returns: a newly created Itdb_PhotoDB to be freed with
  * itdb_photodb_free() when it's no longer needed. The Photo Library
  * Album is created automatically.
- **/
+ *
+ * Since: 0.4.2
+ */
 Itdb_PhotoDB *itdb_photodb_create (const gchar *mountpoint)
 {
     Itdb_PhotoDB *photodb = itdb_photodb_new ();
@@ -280,7 +290,9 @@ static Itdb_PhotoDB *itdb_photodb_new (void)
  * @photodb: an #Itdb_PhotoDB
  *
  * Free the memory taken by @photodb.
- **/
+ *
+ * Since: 0.4.0
+ */
 void itdb_photodb_free (Itdb_PhotoDB *photodb)
 {
 	if (photodb)
@@ -460,24 +472,26 @@ static Itdb_Artwork *itdb_photodb_add_photo_internal (Itdb_PhotoDB *db,
 
 /**
  * itdb_photodb_add_photo:
- * @db: the #Itdb_PhotoDB to add the photo to.
- * @filename: file with the photo to add.
- * @position: position where to insert the new photo (-1 to append at
- * the end)
- * @rotation: angle by which the image should be rotated
- * counterclockwise. Valid values are 0, 90, 180 and 270.
- * @error: return location for a #GError or NULL
- * 
+ * @db:         the #Itdb_PhotoDB to add the photo to
+ * @filename:   path of the photo to add.
+ * @position:   position where to insert the new photo (-1 to append
+ *              at the end)
+ * @rotation:   angle by which the image should be rotated
+ *              counterclockwise. Valid values are 0, 90, 180 and 270.
+ * @error:      return location for a #GError or NULL
+ *
  * Add a photo to the PhotoDB. The photo is automatically added to the
  * first Photoalbum, which by default contains a list of all photos in
  * the database. If no Photoalbums exist one is created automatically.
  *
  * For the rotation angle you can also use the gdk constants
- * GDK_PIXBUF_ROTATE_NONE, ..._COUNTERCLOCKWISE, ..._UPSIDEDOWN AND
- * ..._CLOCKWISE.
+ * %GDK_PIXBUF_ROTATE_NONE, %GDK_PIXBUF_ROTATE_COUNTERCLOCKWISE,
+ * %GDK_PIXBUF_ROTATE_UPSIDEDOWN, AND %GDK_PIXBUF_ROTATE_CLOCKWISE.
  *
- * Return value: a pointer to the added photo.
- **/
+ * Returns: a pointer to the added photo.
+ *
+ * Since: 0.4.0
+ */
 Itdb_Artwork *itdb_photodb_add_photo (Itdb_PhotoDB *db,
 				      const gchar *filename,
 				      gint position,
@@ -493,26 +507,28 @@ Itdb_Artwork *itdb_photodb_add_photo (Itdb_PhotoDB *db,
 
 /**
  * itdb_photodb_add_photo_from_data:
- * @db: the #Itdb_PhotoDB to add the photo to.
- * @image_data: chunk of memory containing the image data (for example
- * a jpg file)
+ * @db:             the #Itdb_PhotoDB to add the photo to
+ * @image_data:     chunk of memory containing the image data (for
+ *                  example a jpg file)
  * @image_data_len: length of above chunk of memory
- * @position: position where to insert the new photo (-1 to append at
- * the end)
- * @rotation: angle by which the image should be rotated
- * counterclockwise. Valid values are 0, 90, 180 and 270.
- * @error: return location for a #GError or NULL
- * 
+ * @position:       position where to insert the new photo (-1 to
+ *                  append at the end)
+ * @rotation:       angle by which the image should be rotated
+ *                  counterclockwise. Valid values are 0, 90, 180 and 270.
+ * @error:          return location for a #GError or NULL
+ *
  * Add a photo to the PhotoDB. The photo is automatically added to the
  * first Photoalbum, which by default contains a list of all photos in
  * the database. If no Photoalbums exist one is created automatically.
  *
  * For the rotation angle you can also use the gdk constants
- * GDK_PIXBUF_ROTATE_NONE, ..._COUNTERCLOCKWISE, ..._UPSIDEDOWN AND
- * ..._CLOCKWISE.
+ * %GDK_PIXBUF_ROTATE_NONE, %GDK_PIXBUF_ROTATE_COUNTERCLOCKWISE,
+ * %GDK_PIXBUF_ROTATE_UPSIDEDOWN, AND %GDK_PIXBUF_ROTATE_CLOCKWISE.
  *
- * Return value: a pointer to the added photo.
- **/
+ * Returns: a pointer to the added photo.
+ *
+ * Since: 0.4.0
+ */
 Itdb_Artwork *itdb_photodb_add_photo_from_data (Itdb_PhotoDB *db,
 						const guchar *image_data,
 						gsize image_data_len,
@@ -530,24 +546,26 @@ Itdb_Artwork *itdb_photodb_add_photo_from_data (Itdb_PhotoDB *db,
 
 /**
  * itdb_photodb_add_photo_from_pixbuf:
- * @db: the #Itdb_PhotoDB to add the photo to.
- * @pixbuf: a #GdkPixbuf to use as the image data
- * @position: position where to insert the new photo (-1 to append at
- * the end)
- * @rotation: angle by which the image should be rotated
- * counterclockwise. Valid values are 0, 90, 180 and 270.
- * @error: return location for a #GError or NULL
- * 
+ * @db:         the #Itdb_PhotoDB to add the photo to
+ * @pixbuf:     a #GdkPixbuf to use as the image data
+ * @position:   position where to insert the new photo (-1 to append
+ *              at the end)
+ * @rotation:   angle by which the image should be rotated
+ *              counterclockwise. Valid values are 0, 90, 180 and 270.
+ * @error:      return location for a #GError or NULL
+ *
  * Add a photo to the PhotoDB. The photo is automatically added to the
  * first Photoalbum, which by default contains a list of all photos in
  * the database. If no Photoalbums exist one is created automatically.
  *
  * For the rotation angle you can also use the gdk constants
- * GDK_PIXBUF_ROTATE_NONE, ..._COUNTERCLOCKWISE, ..._UPSIDEDOWN AND
- * ..._CLOCKWISE.
+ * %GDK_PIXBUF_ROTATE_NONE, %GDK_PIXBUF_ROTATE_COUNTERCLOCKWISE,
+ * %GDK_PIXBUF_ROTATE_UPSIDEDOWN, AND %GDK_PIXBUF_ROTATE_CLOCKWISE.
+ *
+ * Returns: a pointer to the added photo.
  *
- * Return value: a pointer to the added photo.
- **/
+ * Since: 0.5.0
+ */
 Itdb_Artwork *itdb_photodb_add_photo_from_pixbuf (Itdb_PhotoDB *db,
 						  gpointer pixbuf,
 						  gint position,
@@ -563,19 +581,23 @@ Itdb_Artwork *itdb_photodb_add_photo_from_pixbuf (Itdb_PhotoDB *db,
 
 /**
  * itdb_photodb_remove_photo:
- * @db: the #Itdb_PhotoDB to remove the photo from
- * @album: the album to remove the photo from. If album is NULL, then
- * it will first be removed from all photoalbums and then from the
- * photo database as well.
- * @photo: #Itdb_Artwork (photo) to remove.
+ * @db:     the #Itdb_PhotoDB to remove the photo from
+ * @album:  the album to remove the photo from. If album is NULL, then
+ *          it will first be removed from all photoalbums and then
+ *          from the photo database as well.
+ * @photo:  #Itdb_Artwork (photo) to remove.
  *
- * Remove photo. If @album is not the first photoalbum, the photo will
- * be removed from that album only. If @album is NULL or the first
- * photoalbum (Photo Library), the photo will be removed from all
- * albums and the #Itdb_PhotoDB.
+ * Removes a photo. If @album is not the first photoalbum, the photo
+ * will be removed from that album only. If @album is NULL or the
+ * first photoalbum (Photo Library), the photo will be removed from
+ * all albums and the #Itdb_PhotoDB.
  *
+ * <note>
  * @photo will be freed and can no longer be used if removed from the
  * first photoalbum.
+ * </note>
+ *
+ * Since: 0.4.0
  */
 void itdb_photodb_remove_photo (Itdb_PhotoDB *db,
 				Itdb_PhotoAlbum *album,
@@ -609,15 +631,17 @@ void itdb_photodb_remove_photo (Itdb_PhotoDB *db,
 
 /**
  * itdb_photodb_photoalbum_by_name:
- * @db: the #Itdb_PhotoDB to retrieve the album from
- * @albumname: the name of the photoalbum to get or NULL for the
- * master photoalbum.
+ * @db:         the #Itdb_PhotoDB to retrieve the album from
+ * @albumname:  the name of the photoalbum to get or NULL for the
+ *              master photoalbum.
  *
  * Find the first photoalbum with a given name or the Photo Library
  * Album if called with no name.
  *
- * Return value: a pointer to the first photoalbum named @albumname,
+ * Returns: a pointer to the first photoalbum named @albumname,
  * else NULL
+ *
+ * Since: 0.4.2
  */
 Itdb_PhotoAlbum *itdb_photodb_photoalbum_by_name (Itdb_PhotoDB *db, const gchar *albumname)
 {
@@ -638,17 +662,21 @@ Itdb_PhotoAlbum *itdb_photodb_photoalbum_by_name (Itdb_PhotoDB *db, const gchar
 
 /**
  * itdb_photodb_photoalbum_remove:
- * @db: the #Itdb_PhotoDB to apply changes to
- * @album: the album to be removed from the database
- * @remove_pics: TRUE to remove pics in that album permanently from
- * the database.
+ * @db:             the #Itdb_PhotoDB to apply changes to
+ * @album:          the album to be removed from the database
+ * @remove_pics:    TRUE to remove pics in that album permanently
+ *                  from the database.
  *
- * Remove @album from the Photo Database. If remove_pics is TRUE,
+ * Remove @album from the Photo Database. If @remove_pics is TRUE,
  * remove all photos contained in @album from the Photo Database.
  *
+ * <note>
  * Memory used by the removed album will be freed and the album cannot
  * be accessed any more.
- **/
+ * </note>
+ *
+ * Since: 0.4.2
+ */
 void itdb_photodb_photoalbum_remove (Itdb_PhotoDB *db,
 				     Itdb_PhotoAlbum *album,
 				     gboolean remove_pics)
@@ -677,11 +705,12 @@ void itdb_photodb_photoalbum_remove (Itdb_PhotoDB *db,
 
 /**
  * itdb_photodb_photoalbum_add_photo:
- * @db: the #Itdb_PhotoDB to act on
- * @album: the #Itdb_PhotoAlbum to add the photo to
- * @photo: a pointer to the photo (#Itdb_Artwork) to add to the album
- * @position: position where to insert the new photo (-1 to append at
- * the end)
+ * @db:         the #Itdb_PhotoDB to act on
+ * @album:      the #Itdb_PhotoAlbum to add the photo to
+ * @photo:      a pointer to the photo (#Itdb_Artwork) to add to the
+ *              album
+ * @position:   position where to insert the new photo (-1 to append
+ *              at the end)
  *
  * Adds a photo already in the library to the specified album
  * @album. Photos are automatically added to the first album (Photo
@@ -689,8 +718,8 @@ void itdb_photodb_photoalbum_remove (Itdb_PhotoDB *db,
  * itdb_photodb_add_photo_from_data(), so you don't have to use this
  * function to add them there.
  *
+ * Since: 0.4.2
  */
-
 void itdb_photodb_photoalbum_add_photo (Itdb_PhotoDB *db,
 					Itdb_PhotoAlbum *album,
 					Itdb_Artwork *photo,
@@ -705,14 +734,16 @@ void itdb_photodb_photoalbum_add_photo (Itdb_PhotoDB *db,
 
 /**
  * itdb_photodb_photoalbum_create:
- * @db: The database to create a new album in
- * @albumname: the name of the new album
- * @pos: position where to insert the newly created album (-1 for
- * append to end).
+ * @db:         The database to create a new album in
+ * @albumname:  the name of the new album
+ * @pos:        position where to insert the newly created album (-1
+ *              to append at the end).
  *
  * Create and add a new photoalbum.
  *
- * Return value: the album which was created and added.
+ * Returns: the album which was created and added.
+ *
+ * Since: 0.4.2
  */
 Itdb_PhotoAlbum *itdb_photodb_photoalbum_create (Itdb_PhotoDB *db,
 						 const gchar *albumname,
@@ -734,16 +765,18 @@ Itdb_PhotoAlbum *itdb_photodb_photoalbum_create (Itdb_PhotoDB *db,
 
 /**
  * itdb_photodb_write:
- * @photodb: the #Itdb_PhotoDB to write to disk
- * @error: return location for a #GError or NULL
+ * @photodb:    the #Itdb_PhotoDB to write to disk
+ * @error:      return location for a #GError or NULL
  *
  * Write out a PhotoDB.
  *
  * FIXME: error is not set yet.
  *
- * Return value: TRUE on success, FALSE on error, in which case @error is
+ * Returns: TRUE on success, FALSE on error, in which case @error is
  * set accordingly.
- **/
+ *
+ * Since: 0.4.0
+ */
 gboolean itdb_photodb_write (Itdb_PhotoDB *photodb, GError **error)
 {
     gint result;
diff --git a/src/itdb_playlist.c b/src/itdb_playlist.c
index 9acd695..e5c9e6b 100644
--- a/src/itdb_playlist.c
+++ b/src/itdb_playlist.c
@@ -39,13 +39,13 @@
 
 /**
  * itdb_spl_action_known:
- * @action: an #SPLAction
+ * @action: an #ItdbSPLAction
  *
  * Checks if @action is a known (to libgpod) smart playlist action.
  *
- * Return value: TRUE if @action is known. Otherwise a warning is displayed 
- * and FALSE is returned. 
- **/
+ * Returns: TRUE if @action is known. Otherwise a warning is
+ * displayed and FALSE is returned.
+ */
 gboolean itdb_spl_action_known (ItdbSPLAction action)
 {
     gboolean result = FALSE;
@@ -86,9 +86,9 @@ gboolean itdb_spl_action_known (ItdbSPLAction action)
  *
  * Gets the type of the field of the @splr rule
  *
- * Return value: an #Itdb_SPLFieldType corresponding to @splr field type 
- * (string, int, date, ...)
- **/
+ * Returns: an #Itdb_SPLFieldType corresponding to @splr field
+ * type (string, int, date, ...)
+ */
 ItdbSPLFieldType itdb_splr_get_field_type (const Itdb_SPLRule *splr)
 {
     g_return_val_if_fail (splr != NULL, ITDB_SPLFT_UNKNOWN);
@@ -141,8 +141,8 @@ ItdbSPLFieldType itdb_splr_get_field_type (const Itdb_SPLRule *splr)
  *
  * Gets the type of the action associated with @splr.
  *
- * Return value: type (range, date, string...) of the action field
- **/
+ * Returns: type (range, date, string...) of the action field
+ */
 ItdbSPLActionType itdb_splr_get_action_type (const Itdb_SPLRule *splr)
 {
     ItdbSPLFieldType fieldType;
@@ -320,13 +320,13 @@ ItdbSPLActionType itdb_splr_get_action_type (const Itdb_SPLRule *splr)
 
 /**
  * itdb_splr_eval:
- * @splr: an #Itdb_SPLRule
- * @track: an #Itdb_Track
+ * @splr:   an #Itdb_SPLRule
+ * @track:  an #Itdb_Track
  *
- * Evaluates @splr's truth against @track. track-&gt;itdb must be set.
+ * Evaluates @splr's truth against @track. @track->itdb must be set.
  *
- * Return value: TRUE if @track matches @splr, FALSE otherwise.
- **/
+ * Returns: TRUE if @track matches @splr, FALSE otherwise.
+ */
 gboolean itdb_splr_eval (Itdb_SPLRule *splr, Itdb_Track *track)
 {
     ItdbSPLFieldType ft;
@@ -681,7 +681,7 @@ static GList *randomize_glist (GList *list)
  * @pl: an #Itdb_Playlist to randomize
  *
  * Randomizes @pl
- **/
+ */
 void itdb_playlist_randomize (Itdb_Playlist *pl)
 {
     g_return_if_fail (pl);
@@ -693,11 +693,12 @@ void itdb_playlist_randomize (Itdb_Playlist *pl)
  * itdb_spl_update:
  * @spl: an #Itdb_Playlist
  *
- * Updates the content of the smart playlist @spl (meant to be called if the 
- * tracks stored in the #Itdb_iTunesDB associated with @spl have changed 
- * somehow and you want spl-&gt;members to be accurate with regards to those 
- * changes. Does nothing if @spl isn't a smart playlist.
- **/
+ * Updates the content of the smart playlist @spl (meant to be called
+ * if the tracks stored in the #Itdb_iTunesDB associated with @spl
+ * have changed somehow and you want @spl->members to be accurate
+ * with regards to those changes. Does nothing if @spl isn't a smart
+ * playlist.
+ */
 void itdb_spl_update (Itdb_Playlist *spl)
 {
     GList *gl;
@@ -909,7 +910,7 @@ void itdb_spl_update (Itdb_Playlist *spl)
  * @itdb: an #Itdb_iTunesDB
  *
  * Updates all smart playlists contained in @itdb
- **/
+ */
 void itdb_spl_update_all (Itdb_iTunesDB *itdb)
 {
     g_return_if_fail (itdb);
@@ -929,9 +930,11 @@ static void spl_update2 (Itdb_Playlist *playlist, gpointer data)
  * itdb_spl_update_live:
  * @itdb: an #Itdb_iTunesDB
  *
- * Updates all 'live' smart playlists contained in @itdb, ie those which have 
- * the 'live updating' flag set
- **/
+ * Updates all smart playlists contained in @itdb which have the
+ * @liveupdate flag set.
+ *
+ * Since: 0.2.0
+ */
 void itdb_spl_update_live (Itdb_iTunesDB *itdb)
 {
     g_return_if_fail (itdb);
@@ -947,8 +950,8 @@ void itdb_spl_update_live (Itdb_iTunesDB *itdb)
  * itdb_splr_validate:
  * @splr: an #Itdb_SPLRule
  *
- * Validates a rule 
- **/
+ * Validates a smart playlist rule
+ */
 void itdb_splr_validate (Itdb_SPLRule *splr)
 {
     ItdbSPLActionType at;
@@ -1005,7 +1008,7 @@ void itdb_splr_validate (Itdb_SPLRule *splr)
  * @splr: an #Itdb_SPLRule
  *
  * Frees the memory used by @splr
- **/
+ */
 void itdb_splr_free (Itdb_SPLRule *splr)
 {
     if (splr)
@@ -1020,9 +1023,9 @@ void itdb_splr_free (Itdb_SPLRule *splr)
  * @pl: an #Itdb_Playlist
  * @splr: an Itdb_SPLRule
  *
- * Removes the smart playlist rule @splr from playlist @pl. The memory used by
- * @splr is freed.
- **/
+ * Removes the smart playlist rule @splr from playlist @pl. The memory
+ * used by @splr is freed.
+ */
 void itdb_splr_remove (Itdb_Playlist *pl, Itdb_SPLRule *splr)
 {
     g_return_if_fail (pl);
@@ -1034,14 +1037,14 @@ void itdb_splr_remove (Itdb_Playlist *pl, Itdb_SPLRule *splr)
 
 /**
  * itdb_splr_add:
- * @pl: an #Itdb_Playlist
- * @splr: an #Itdb_SPLRule
- * @pos: position of the rule
+ * @pl:     an #Itdb_Playlist
+ * @splr:   an #Itdb_SPLRule
+ * @pos:    position of the rule
  *
- * Adds the smart rule @splr to @pl at position @pos. If @pos is -1, @splr gets
- * appended to the end. After this call, @splr memory is managed by @pl, so 
- * you no longer need to call itdb_splr_free()
- **/
+ * Adds the smart rule @splr to @pl at position @pos. If @pos is -1,
+ * @splr gets appended to the end. After this call, @splr memory is
+ * managed by @pl, so you no longer need to call itdb_splr_free()
+ */
 void itdb_splr_add (Itdb_Playlist *pl, Itdb_SPLRule *splr, gint pos)
 {
     g_return_if_fail (pl);
@@ -1056,9 +1059,9 @@ void itdb_splr_add (Itdb_Playlist *pl, Itdb_SPLRule *splr, gint pos)
  *
  * Creates a new default smart rule
  *
- * Return value: a new #Itdb_SPLRule that must be freed with itdb_splr_free() when
+ * Returns: a new #Itdb_SPLRule that must be freed with itdb_splr_free() when
  * no longer needed
- **/
+ */
 Itdb_SPLRule *itdb_splr_new (void)
 {
     Itdb_SPLRule *splr = g_new0 (Itdb_SPLRule, 1);
@@ -1077,15 +1080,16 @@ Itdb_SPLRule *itdb_splr_new (void)
 
 /**
  * itdb_splr_add_new:
- * @pl: an #Itdb_Playlist
- * @pos: position to insert the rule at
+ * @pl:     an #Itdb_Playlist
+ * @pos:    position to insert the rule at
  *
- * Creates a new smart rule and inserts it at position @pos in @pl. If @pos is
- * -1, the new rule gets appended to the end.
+ * Creates a new smart rule and inserts it at position @pos in @pl. If
+ * @pos is -1, the new rule gets appended to the end.
  *
- * Return value: pointer to the newly created #Itdb_SPLRule. Its memory is handled 
- * by @pl though, so you don't need to explicitly call itdb_splr_free() on it
- **/
+ * Returns: pointer to the newly created #Itdb_SPLRule. Its
+ * memory is handled by @pl though, so you don't need to explicitly
+ * call itdb_splr_free() on it
+ */
 Itdb_SPLRule *itdb_splr_add_new (Itdb_Playlist *pl, gint pos)
 {
     Itdb_SPLRule *splr;
@@ -1116,13 +1120,14 @@ static Itdb_SPLRule *splr_duplicate (Itdb_SPLRule *splr)
  * itdb_playlist_duplicate:
  * @pl: an #Itdb_Playlist
  *
- * Duplicates an existing playlist. pl_dup-&gt;id is set to zero, so that
- * it will be set to a unique value when adding it to an #Itdb_iTunesDB. The
- * returned playlist won't be associated with an #Itdb_iTunesDB.
+ * Duplicates an existing playlist. @pl_dup->id is set to zero, so
+ * that it will be set to a unique value when adding it to an
+ * #Itdb_iTunesDB. The returned playlist won't be associated with an
+ * #Itdb_iTunesDB.
  *
- * Return value: a newly allocated #Itdb_Playlist that you'll have to free
- * with itdb_playlist_free() when you no longer need it. 
- **/
+ * Returns: a newly allocated #Itdb_Playlist that you'll have to
+ * free with itdb_playlist_free() when you no longer need it.
+ */
 Itdb_Playlist *itdb_playlist_duplicate (Itdb_Playlist *pl)
 {
     Itdb_Playlist *pl_dup;
@@ -1166,13 +1171,13 @@ Itdb_Playlist *itdb_playlist_duplicate (Itdb_Playlist *pl)
 
 /**
  * itdb_spl_copy_rules:
- * @dest: destination #Itdb_Playlist
- * @src: source #Itdb_Playlist
+ * @dest:   destination #Itdb_Playlist
+ * @src:    source #Itdb_Playlist
  *
  * Copy all relevant information for smart playlist from playlist @src
- * to playlist @dest. If @dest is already a smart playlist, the existing data
- * is overwritten/deleted. 
- **/
+ * to playlist @dest. If @dest is already a smart playlist, the
+ * existing data is overwritten/deleted.
+ */
 void itdb_spl_copy_rules (Itdb_Playlist *dest, Itdb_Playlist *src)
 {
     GList *gl;
@@ -1202,16 +1207,16 @@ void itdb_spl_copy_rules (Itdb_Playlist *dest, Itdb_Playlist *src)
 
 /**
  * itdb_playlist_new:
- * @title: playlist title
- * @spl: smart playlist flag
- *
- * Creates a new playlist. If @spl is TRUE, a smart
- * playlist is generated. pl->id is set by itdb_playlist_add() when the 
- * playlist is added to an #Itdb_iTunesDB
- * 
- * Return value: a new #Itdb_Playlist which must be freed with 
+ * @title:  playlist title
+ * @spl:    smart playlist flag
+ *
+ * Creates a new playlist. If @spl is TRUE, a smart playlist is
+ * generated. pl->id is set by itdb_playlist_add() when the playlist
+ * is added to an #Itdb_iTunesDB
+ *
+ * Returns: a new #Itdb_Playlist which must be freed with
  * itdb_playlist_free() after use
- **/
+ */
 Itdb_Playlist *itdb_playlist_new (const gchar *title, gboolean spl)
 {
     Itdb_Playlist *pl = g_new0 (Itdb_Playlist, 1);
@@ -1244,7 +1249,7 @@ Itdb_Playlist *itdb_playlist_new (const gchar *title, gboolean spl)
  * @pl: an #Itdb_Playlist
  *
  * Frees the memory used by playlist @pl.
- **/
+ */
 void itdb_playlist_free (Itdb_Playlist *pl)
 {
     g_return_if_fail (pl);
@@ -1260,15 +1265,16 @@ void itdb_playlist_free (Itdb_Playlist *pl)
 
 /**
  * itdb_playlist_add:
- * @itdb: an #Itdb_iTunesDB
- * @pl: an #Itdb_Playlist
- * @pos: position to insert @pl at
+ * @itdb:   an #Itdb_iTunesDB
+ * @pl:     an #Itdb_Playlist
+ * @pos:    position to insert @pl at
  *
  * Adds playlist @pl to the database @itdb at position @pos (-1 for
- * "append to end"). A unique id is created if pl-&gt;id is equal to
- * zero. After calling this function, @itdb manages the memory of @pl, which
- * means you no longer need to explicitly call itdb_playlist_free()
- **/
+ * "append to end"). A unique id is created if @pl->id is equal to
+ * zero. After calling this function, @itdb manages the memory of @pl,
+ * which means you no longer need to explicitly call
+ * itdb_playlist_free()
+ */
 void itdb_playlist_add (Itdb_iTunesDB *itdb, Itdb_Playlist *pl, gint32 pos)
 {
     g_return_if_fail (itdb);
@@ -1307,11 +1313,11 @@ void itdb_playlist_add (Itdb_iTunesDB *itdb, Itdb_Playlist *pl, gint32 pos)
 
 /**
  * itdb_playlist_move:
- * @pl: an #Itdb_Playlist
- * @pos: new position
+ * @pl:     an #Itdb_Playlist
+ * @pos:    new position
  *
  * Moves playlist @pl to position @pos
- **/
+ */
 void itdb_playlist_move (Itdb_Playlist *pl, guint32 pos)
 {
     Itdb_iTunesDB *itdb;
@@ -1330,7 +1336,7 @@ void itdb_playlist_move (Itdb_Playlist *pl, guint32 pos)
  *
  * Removes @pl from the #Itdb_iTunesDB it's associated with
  * and frees memory
- **/
+ */
 void itdb_playlist_remove (Itdb_Playlist *pl)
 {
     Itdb_iTunesDB *itdb;
@@ -1347,9 +1353,9 @@ void itdb_playlist_remove (Itdb_Playlist *pl)
  * itdb_playlist_unlink:
  * @pl: an #Itdb_Playlist
  *
- * Remove @pl from the #Itdb_iTunesDB it's associated with but do not free 
- * memory. pl-&gt;itdb is set to NULL after this function returns
- **/
+ * Remove @pl from the #Itdb_iTunesDB it's associated with but do not
+ * free memory. @pl->itdb is set to NULL after this function returns
+ */
 void itdb_playlist_unlink (Itdb_Playlist *pl)
 {
     Itdb_iTunesDB *itdb;
@@ -1364,13 +1370,13 @@ void itdb_playlist_unlink (Itdb_Playlist *pl)
 
 /**
  * itdb_playlist_exists:
- * @itdb: an #Itdb_iTunesDB
- * @pl: an #Itdb_Playlist
+ * @itdb:   an #Itdb_iTunesDB
+ * @pl:     an #Itdb_Playlist
  *
- * Checks if @pl is present in @db
+ * Checks if @pl is present in @itdb
  *
- * Return value: TRUE if @pl exists in @db, FALSE otherwise 
- **/
+ * Returns: TRUE if @pl exists in @itdb, FALSE otherwise
+ */
 gboolean itdb_playlist_exists (Itdb_iTunesDB *itdb, Itdb_Playlist *pl)
 {
     g_return_val_if_fail (itdb, FALSE);
@@ -1382,13 +1388,12 @@ gboolean itdb_playlist_exists (Itdb_iTunesDB *itdb, Itdb_Playlist *pl)
 
 /**
  * itdb_playlist_add_track:
- * @pl: an #Itdb_Playlist
- * @track: an #Itdb_Track
- * @pos: position to insert @track at
+ * @pl:     an #Itdb_Playlist
+ * @track:  an #Itdb_Track
+ * @pos:    position to insert @track at
  *
- * Adds @track to @pl at position @pos (-1 for "append to
- * end") 
- **/
+ * Adds @track to @pl at position @pos (-1 to append at the end)
+ */
 void itdb_playlist_add_track (Itdb_Playlist *pl,
 			      Itdb_Track *track, gint32 pos)
 {
@@ -1403,14 +1408,14 @@ void itdb_playlist_add_track (Itdb_Playlist *pl,
 
 /**
  * itdb_playlist_remove_track:
- * @pl: an #Itdb_Playlist
- * @track: an #Itdb_Track
+ * @pl:     an #Itdb_Playlist
+ * @track:  an #Itdb_Track
  *
  * Removes @track from @pl. If @pl is NULL, removes @track from the
- * master playlist. If @track can't be found in @pl, nothing happens. If after
- * removing @track, @pl is empty, it's not removed from the database
- * The memory used by @track isn't freed.
- **/
+ * master playlist. If @track can't be found in @pl, nothing happens.
+ * If after removing @track, @pl is empty, it's not removed from the
+ * database The memory used by @track isn't freed.
+ */
 void itdb_playlist_remove_track (Itdb_Playlist *pl, Itdb_Track *track)
 {
     g_return_if_fail (track);
@@ -1425,14 +1430,14 @@ void itdb_playlist_remove_track (Itdb_Playlist *pl, Itdb_Track *track)
 
 /**
  * itdb_playlist_by_id:
- * @itdb: an #Itdb_iTunesDB
- * @id: ID of the playlist to look for
+ * @itdb:   an #Itdb_iTunesDB
+ * @id:     ID of the playlist to look for
  *
  * Looks up a playlist whose ID is @id
  *
- * Return value: the #Itdb_Playlist with ID @id or NULL if there is no such
- * playlist.
- **/
+ * Returns: the #Itdb_Playlist with ID @id or NULL if there is no
+ * such playlist.
+ */
 Itdb_Playlist *itdb_playlist_by_id (Itdb_iTunesDB *itdb, guint64 id)
 {
     GList *gl;
@@ -1449,13 +1454,14 @@ Itdb_Playlist *itdb_playlist_by_id (Itdb_iTunesDB *itdb, guint64 id)
 
 /**
  * itdb_playlist_by_nr:
- * @itdb: an #Itdb_iTunesDB
- * @num: the position of the playlist, counting from 0
+ * @itdb:   an #Itdb_iTunesDB
+ * @num:    the position of the playlist, counting from 0
  *
  * Gets the playlist at the given position in @itdb
  *
- * Return value: the #Itdb_Playlist, or NULL if there is no playlist at @pos
- **/
+ * Returns: the #Itdb_Playlist, or NULL if there is no playlist
+ * at @pos
+ */
 Itdb_Playlist *itdb_playlist_by_nr (Itdb_iTunesDB *itdb, guint32 num)
 {
     Itdb_Playlist *pl;
@@ -1467,14 +1473,14 @@ Itdb_Playlist *itdb_playlist_by_nr (Itdb_iTunesDB *itdb, guint32 num)
 
 /**
  * itdb_playlist_by_name:
- * @itdb: an #Itdb_iTunesDB
- * @name: name of the playlist to look for
+ * @itdb:   an #Itdb_iTunesDB
+ * @name:   name of the playlist to look for
  *
  * Searches a playlist whose name is @name in @itdb
  *
- * Return value: the first #Itdb_Playlist with name @name, NULL if there is no
- * such playlist
- **/
+ * Returns: the first #Itdb_Playlist with name @name, NULL if
+ * there is no such playlist
+ */
 Itdb_Playlist *itdb_playlist_by_name (Itdb_iTunesDB *itdb, gchar *name)
 {
     GList *gl;
@@ -1497,8 +1503,10 @@ Itdb_Playlist *itdb_playlist_by_name (Itdb_iTunesDB *itdb, gchar *name)
  *
  * Checks if @pl is the master playlist
  *
- * Return value: TRUE if @pl is the master playlist, FALSE otherwise
- **/
+ * Returns: TRUE if @pl is the master playlist, FALSE otherwise
+ *
+ * Since: 0.1.6
+ */
 gboolean itdb_playlist_is_mpl (Itdb_Playlist *pl)
 {
     g_return_val_if_fail (pl, FALSE);
@@ -1512,8 +1520,10 @@ gboolean itdb_playlist_is_mpl (Itdb_Playlist *pl)
  *
  * Checks if @pl is the podcasts playlist
  *
- * Return value: TRUE if @pl is the podcasts playlist, FALSE otherwise
- **/
+ * Returns: TRUE if @pl is the podcasts playlist, FALSE otherwise
+ *
+ * Since: 0.1.6
+ */
 gboolean itdb_playlist_is_podcasts (Itdb_Playlist *pl)
 {
     g_return_val_if_fail (pl, FALSE);
@@ -1526,7 +1536,9 @@ gboolean itdb_playlist_is_podcasts (Itdb_Playlist *pl)
  * @pl: an #Itdb_Playlist
  *
  * Sets @pl to be a master playlist
- **/
+ *
+ * Since: 0.2.0
+ */
 void itdb_playlist_set_mpl (Itdb_Playlist *pl)
 {
     g_return_if_fail (pl);
@@ -1539,7 +1551,9 @@ void itdb_playlist_set_mpl (Itdb_Playlist *pl)
  * @pl: an #Itdb_Playlist
  *
  * Set @pl to be a podcasts playlist
- **/
+ *
+ * Since: 0.2.0
+ */
 void itdb_playlist_set_podcasts (Itdb_Playlist *pl)
 {
     g_return_if_fail (pl);
@@ -1553,8 +1567,8 @@ void itdb_playlist_set_podcasts (Itdb_Playlist *pl)
  *
  * Gets the master playlist of @itdb
  *
- * Return value: the master playlist of @itdb
- **/
+ * Returns: the master playlist of @itdb
+ */
 Itdb_Playlist *itdb_playlist_mpl (Itdb_iTunesDB *itdb)
 {
     Itdb_Playlist *pl;
@@ -1570,15 +1584,17 @@ Itdb_Playlist *itdb_playlist_mpl (Itdb_iTunesDB *itdb)
     return pl;
 }
 
-
 /**
  * itdb_playlist_podcasts:
  * @itdb: an #Itdb_iTunesDB
  *
  * Gets the podcasts playlist of @itdb
  *
- * Return value: the podcasts playlist of @itdb, or NULL if it's there is none
- **/
+ * Returns: the podcasts playlist of @itdb, or NULL if there is
+ * not one
+ *
+ * Since: 0.1.6
+ */
 Itdb_Playlist *itdb_playlist_podcasts (Itdb_iTunesDB *itdb)
 {
     GList *gl;
@@ -1598,13 +1614,13 @@ Itdb_Playlist *itdb_playlist_podcasts (Itdb_iTunesDB *itdb)
 
 /**
  * itdb_playlist_contains_track:
- * @pl: an #Itdb_Playlist
- * @track: an #Itdb_Track
+ * @pl:     an #Itdb_Playlist
+ * @track:  an #Itdb_Track
  *
- * Checks if @track is in @pl.
- * 
- * Return value: TRUE if @track is in @pl, FALSE otherwise
- **/
+ * Checks if @track is in @pl
+ *
+ * Returns: TRUE if @track is in @pl, FALSE otherwise
+ */
 gboolean itdb_playlist_contains_track (Itdb_Playlist *pl, Itdb_Track *tr)
 {
     g_return_val_if_fail (tr, FALSE);
@@ -1622,11 +1638,11 @@ gboolean itdb_playlist_contains_track (Itdb_Playlist *pl, Itdb_Track *tr)
  * itdb_playlist_contain_track_number:
  * @tr: an #Itdb_Track
  *
- * Counts the number of playlist @track is a member of (not including the 
- * master playlist)
+ * Counts the number of playlist @track is a member of (not including
+ * the master playlist)
  *
- * Return value: number of playlist containing @track
- **/
+ * Returns: the number of playlist containing @track
+ */
 guint32 itdb_playlist_contain_track_number (Itdb_Track *tr)
 {
     Itdb_iTunesDB *itdb;
@@ -1654,8 +1670,8 @@ guint32 itdb_playlist_contain_track_number (Itdb_Track *tr)
  *
  * Counts the number of tracks in @pl
  *
- * Return value: track count
- **/
+ * Returns: the number of tracks in @pl
+ */
 guint32 itdb_playlist_tracks_number (Itdb_Playlist *pl)
 {
     g_return_val_if_fail (pl, 0);
diff --git a/src/itdb_plist.c b/src/itdb_plist.c
index 2bd1dca..6595401 100644
--- a/src/itdb_plist.c
+++ b/src/itdb_plist.c
@@ -373,15 +373,16 @@ itdb_plist_parse (xmlNode * a_node, GError **error)
 
 /**
  * itdb_plist_parse:
- * @filename: name of the XML plist file to parse
- * @error: return location for a #GError
+ * @filename:   name of the XML plist file to parse
+ * @error:      return location for a #GError
  *
- * Returns: NULL on error (@error will be set), a newly allocated GValue
- * containing a GHashTable otherwise.
+ * Parses the XML plist file stored in @filename. If an error occurs
+ * during the parsing, itdb_plist_parse will return NULL and @error
+ * will be set
  *
- * Parses the XML plist file stored in @filename. If an error occurs during
- * the parsing, itdb_plist_parse will return NULL and @error will be set
- **/
+ * Returns: NULL on error (@error will be set), a newly allocated
+ * #GValue containing a #GHashTable otherwise.
+ */
 GValue *
 itdb_plist_parse_from_file (const char *filename, GError **error)
 {
@@ -409,17 +410,18 @@ itdb_plist_parse_from_file (const char *filename, GError **error)
 
 /**
  * itdb_plist_parse_from_memory:
- * @data: memory location containing XML plist data to parse
- * @len: length in bytes of the string to parse
- * @error: return location for a #GError
+ * @data:   memory location containing XML plist data to parse
+ * @len:    length in bytes of the string to parse
+ * @error:  return location for a #GError
  *
- * Returns: NULL on error (@error will be set), a newly allocated GValue
- * containing a GHashTable otherwise.
+ * Parses the XML plist file stored in @data which length is @len
+ * bytes. If an error occurs during the parsing,
+ * itdb_plist_parse_from_memory() will return NULL and @error will be
+ * set.
  *
- * Parses the XML plist file stored in @data which length is @len bytes. If
- * an error occurs during the parsing, itdb_plist_parse_from_memory will
- * return NULL and @error will be set
- **/
+ * Returns: NULL on error (@error will be set), a newly allocated
+ * #GValue containing a #GHashTable otherwise.
+ */
 GValue *
 itdb_plist_parse_from_memory (const char *data, gsize len, GError **error)
 {
diff --git a/src/itdb_sysinfo_extended_parser.c b/src/itdb_sysinfo_extended_parser.c
index 5408c91..a373b8b 100644
--- a/src/itdb_sysinfo_extended_parser.c
+++ b/src/itdb_sysinfo_extended_parser.c
@@ -501,16 +501,18 @@ static SysInfoIpodProperties *g_value_to_ipod_properties (GValue *value)
 
 /**
  * itdb_sysinfo_extended_parse:
- * @filename: name of the SysInfoExtended file to parse
- * @error: return location for a #GError
- * Returns: a newly allocated #SysInfoIpodProperties which must be freed
- * after use, or NULL if an error occurred during the parsing
+ * @filename:   name of the SysInfoExtended file to parse
+ * @error:      return location for a #GError
  *
  * itdb_sysinfo_extended_parse() parses a SysInfoExtended file into a
  * #SysInfoIpodProperties structure. This structure contains a lot of
- * information about the iPod properties (artwork format supported, podcast 
- * capabilities, ...) which can be queried using the appropriate accessors
- **/
+ * information about the iPod properties (artwork format supported,
+ * podcast capabilities, ...) which can be queried using the
+ * appropriate accessors.
+ *
+ * Returns: a newly allocated #SysInfoIpodProperties which must be
+ * freed after use, or NULL if an error occurred during the parsing
+ */
 SysInfoIpodProperties *itdb_sysinfo_extended_parse (const char *filename,
                                                     GError **error)
 {
@@ -534,9 +536,6 @@ SysInfoIpodProperties *itdb_sysinfo_extended_parse (const char *filename,
  * itdb_sysinfo_properties_get_serial_number:
  * @props: a #SysInfoIpodProperties structure
  *
- * Returns: the iPod serial number, NULL if the serial number wasn't set in
- * @props. The returned string must not be modified nor freed.
- *
  * Gets the iPod serial number from @props if it was found while parsing
  * @props. The serial number uniquely identify an ipod and it can be used
  * to determine when it was produced and its model/color, see
@@ -545,7 +544,10 @@ SysInfoIpodProperties *itdb_sysinfo_extended_parse (const char *filename,
  * correspond to. Please avoid parsing this serial number by yourself and
  * ask for additionnal API in libgpod if you find yourself needing to parse
  * that serial number :)
- **/
+ *
+ * Returns: the iPod serial number, NULL if the serial number wasn't set in
+ * @props. The returned string must not be modified nor freed.
+ */
 const char *
 itdb_sysinfo_properties_get_serial_number (const SysInfoIpodProperties *props)
 {
@@ -557,16 +559,16 @@ itdb_sysinfo_properties_get_serial_number (const SysInfoIpodProperties *props)
  * itdb_sysinfo_properties_get_firewire_id:
  * @props: a #SysInfoIpodProperties structure
  *
- * Returns: the iPod firewire ID, NULL if the serial number wasn't set in
- * @props. The returned string must not be modified nor freed.
- *
  * Gets the iPod firewire ID from @props if it was found while parsing
  * @props. Contrary to what its name implies, the firewire ID is also set
  * on USB iPods and is especially important on iPod Classic and Nano Video
  * since this ID (which is unique on each iPod) is needed to generate the
  * checksum that is required to write a valid iPod database on these
  * models.
- **/
+ *
+ * Returns: the iPod firewire ID, NULL if the serial number wasn't set in
+ * @props. The returned string must not be modified nor freed.
+ */
 const char *
 itdb_sysinfo_properties_get_firewire_id (const SysInfoIpodProperties *props)
 {
@@ -578,11 +580,10 @@ itdb_sysinfo_properties_get_firewire_id (const SysInfoIpodProperties *props)
  * itdb_sysinfo_properties_get_cover_art_formats:
  * @props: a #SysInfoIpodProperties structure
  *
- * Returns: a #GList of #Itdb_ArtworkFormat describing the cover art formats 
- * supported by the iPod described in @props. The returned list must not be 
+ * Returns: a #GList of #Itdb_ArtworkFormat describing the cover art formats
+ * supported by the iPod described in @props. The returned list must not be
  * modified nor freed.
- *
- **/
+ */
 const GList *
 itdb_sysinfo_properties_get_cover_art_formats (const SysInfoIpodProperties *props)
 {
@@ -594,11 +595,10 @@ itdb_sysinfo_properties_get_cover_art_formats (const SysInfoIpodProperties *prop
  * itdb_sysinfo_properties_get_photo_formats:
  * @props: a #SysInfoIpodProperties structure
  *
- * Returns: a #GList of #Itdb_ArtworkFormat describing the photo formats 
- * supported by the iPod described in @props. The returned list must not be 
+ * Returns: a #GList of #Itdb_ArtworkFormat describing the photo formats
+ * supported by the iPod described in @props. The returned list must not be
  * modified nor freed.
- *
- **/
+ */
 const GList *
 itdb_sysinfo_properties_get_photo_formats (const SysInfoIpodProperties *props)
 {
@@ -610,11 +610,10 @@ itdb_sysinfo_properties_get_photo_formats (const SysInfoIpodProperties *props)
  * itdb_sysinfo_properties_get_chapter_image_formats:
  * @props: a #SysInfoIpodProperties structure
  *
- * Returns: a #GList of #Itdb_ArtworkFormat describing the chapter image 
- * formats supported by the iPod described in @props. The returned list must 
+ * Returns: a #GList of #Itdb_ArtworkFormat describing the chapter image
+ * formats supported by the iPod described in @props. The returned list must
  * not be modified nor freed.
- *
- **/
+ */
 const GList *
 itdb_sysinfo_properties_get_chapter_image_formats (const SysInfoIpodProperties *props)
 {
@@ -626,13 +625,13 @@ itdb_sysinfo_properties_get_chapter_image_formats (const SysInfoIpodProperties *
  * itdb_sysinfo_properties_supports_sparse_artwork:
  * @props: a #SysInfoIpodProperties structure
  *
- * Returns: TRUE if the iPod supports sparse artwork, FALSE if it does not
- * or if @props doesn't contain any information about sparse artwork
- *
  * Sparse artwork is a way to share artwork between different iPod tracks
  * which make things more efficient space-wise. This function can be used
  * to check if the more space-efficient artwork storage can be used.
- **/
+ *
+ * Returns: TRUE if the iPod supports sparse artwork, FALSE if it does not
+ * or if @props doesn't contain any information about sparse artwork
+ */
 G_GNUC_INTERNAL gboolean
 itdb_sysinfo_properties_supports_sparse_artwork (const SysInfoIpodProperties *props)
 {
diff --git a/src/itdb_thumb.c b/src/itdb_thumb.c
index 201dfb1..0f9a394 100644
--- a/src/itdb_thumb.c
+++ b/src/itdb_thumb.c
@@ -115,7 +115,9 @@ static void itdb_thumb_ipod_item_free (Itdb_Thumb_Ipod_Item *item)
  * @thumb: an #Itdb_Thumb
  *
  * Frees the memory used by @thumb
- **/
+ *
+ * Since: 0.3.0
+ */
 void itdb_thumb_free (Itdb_Thumb *thumb)
 {
     g_return_if_fail (thumb);
@@ -183,9 +185,11 @@ itdb_thumb_ipod_item_duplicate (Itdb_Thumb_Ipod_Item *item)
  *
  * Duplicates the data contained in @thumb
  *
- * Return value: a newly allocated copy of @thumb to be freed with
+ * Returns: a newly allocated copy of @thumb to be freed with
  * itdb_thumb_free() after use
- **/
+ *
+ * Since: 0.3.0
+ */
 Itdb_Thumb *itdb_thumb_duplicate (Itdb_Thumb *thumb)
 {
     switch (thumb->data_type) {
@@ -298,17 +302,17 @@ Itdb_Thumb_Ipod_Item *itdb_thumb_ipod_get_item_by_type (Itdb_Thumb *thumbs,
 }
 
 /**
- * itdb_thumb_get_filename:
+ * itdb_thumb_ipod_get_filename:
  * @device: an #Itdb_Device
- * @thumb: an #Itdb_Thumb
+ * @thumb:  an #Itdb_Thumb_Ipod_Item
  *
  * Get filename of thumbnail. If it's a thumbnail on the iPod, return
  * the full path to the ithmb file. Otherwise return the full path to
  * the original file.
  *
- * Return value: newly allocated string containing the absolute path to the
+ * Returns: newly allocated string containing the absolute path to the
  * thumbnail file.
- **/
+ */
 gchar *itdb_thumb_ipod_get_filename (Itdb_Device *device, Itdb_Thumb_Ipod_Item *item)
 {
     gchar *artwork_dir;
@@ -356,23 +360,26 @@ const GList *itdb_thumb_ipod_get_thumbs (Itdb_Thumb_Ipod *thumbs)
 /**
  * itdb_thumb_to_pixbuf_at_size:
  * @device: an #Itdb_Device
- * @thumb: an #Itdb_Thumb
- * 
+ * @thumb:  an #Itdb_Thumb
+ * @width:  width of the pixbuf to retrieve, -1 for the biggest
+ *          possible size and 0 for the smallest possible size (with no scaling)
+ * @height: height of the pixbuf to retrieve, -1 for the biggest possible size
+ *          and 0 for the smallest possible size (with no scaling)
+ *
  * Converts @thumb to a #GdkPixbuf.
+ *
+ * <note>
  * Since we want to have gdk-pixbuf dependency optional, a generic
  * gpointer is returned which you have to cast to a #GdkPixbuf using
  * GDK_PIXBUF() yourself.
+ * </note>
  *
- * @width: width of the pixbuf to retrieve, -1 for the biggest
- * possible size and 0 for the smallest possible size (with no scaling)
- *
- * @height: height of the pixbuf to retrieve, -1 for the biggest possible size
- * and 0 for the smallest possible size (with no scaling)
- *
- * Return value: a #GdkPixbuf that must be unreffed with gdk_pixbuf_unref()
+ * Returns: a #GdkPixbuf that must be unreffed with gdk_pixbuf_unref()
  * after use, or NULL if the creation of the gdk-pixbuf failed or if
  * libgpod was compiled without gdk-pixbuf support.
- **/
+ *
+ * Since: 0.7.0
+ */
 gpointer itdb_thumb_to_pixbuf_at_size (Itdb_Device *device, Itdb_Thumb *thumb,
                                        gint width, gint height)
 {
@@ -504,7 +511,8 @@ gpointer itdb_thumb_to_pixbuf_at_size (Itdb_Device *device, Itdb_Thumb *thumb,
     return pixbuf;
 }
 
-static GList *itdb_thumb_ipod_to_pixbufs (Itdb_Device *dev, Itdb_Thumb_Ipod *thumb)
+static GList *itdb_thumb_ipod_to_pixbufs (Itdb_Device *device,
+                                          Itdb_Thumb_Ipod *thumb)
 {
         const GList *items;
         GList *pixbufs = NULL;
@@ -516,7 +524,7 @@ static GList *itdb_thumb_ipod_to_pixbufs (Itdb_Device *dev, Itdb_Thumb_Ipod *thu
              items != NULL;
              items = items->next) {
             GdkPixbuf *pixbuf;
-            pixbuf = itdb_thumb_ipod_item_to_pixbuf (dev, items->data);
+            pixbuf = itdb_thumb_ipod_item_to_pixbuf (device, items->data);
             if (pixbuf != NULL) {
                 pixbufs = g_list_prepend (pixbufs, pixbuf);
             }
@@ -528,12 +536,7 @@ static GList *itdb_thumb_ipod_to_pixbufs (Itdb_Device *dev, Itdb_Thumb_Ipod *thu
 /**
  * itdb_thumb_to_pixbufs:
  * @device: an #Itdb_Device
- * @thumb: an #Itdb_Thumb
- * 
- * Return value: a #GList of #GdkPixbuf which are associated with @thumb, NULL
- * if the pixbuf was invalid or if libgpod is compiled without gdk-pixbuf
- * support. The #GdkPixbuf must be unreffed with gdk_pixbuf_unref() after use 
- * and the #GList must be freed with g_list_free().
+ * @thumb:  an #Itdb_Thumb
  *
  * Converts @thumb to a #GList of #GdkPixbuf. The returned #GList will
  * generally contain only 1 element, the full-size pixbuf associated with
@@ -541,20 +544,27 @@ static GList *itdb_thumb_ipod_to_pixbufs (Itdb_Device *dev, Itdb_Thumb_Ipod *thu
  * modified from the library, then the returned #GList will contain several
  * #GdkPixbuf corresponding to the various thumbnail sizes that were
  * written to the iPod database.
- **/
-GList *itdb_thumb_to_pixbufs (Itdb_Device *dev, Itdb_Thumb *thumb)
+ *
+ * Returns: a #GList of #GdkPixbuf which are associated with @thumb, NULL
+ * if the pixbuf was invalid or if libgpod is compiled without gdk-pixbuf
+ * support. The #GdkPixbuf must be unreffed with gdk_pixbuf_unref() after use
+ * and the #GList must be freed with g_list_free().
+ *
+ * Since: 0.7.0
+ */
+GList *itdb_thumb_to_pixbufs (Itdb_Device *device, Itdb_Thumb *thumb)
 {
     GList *pixbufs = NULL;
     GdkPixbuf *pixbuf;
 
     switch (thumb->data_type) {
     case ITDB_THUMB_TYPE_IPOD:
-        pixbufs = itdb_thumb_ipod_to_pixbufs (dev, (Itdb_Thumb_Ipod *)thumb);
+        pixbufs = itdb_thumb_ipod_to_pixbufs (device, (Itdb_Thumb_Ipod *)thumb);
         break;
     case ITDB_THUMB_TYPE_FILE:
     case ITDB_THUMB_TYPE_MEMORY:
     case ITDB_THUMB_TYPE_PIXBUF:
-        pixbuf = itdb_thumb_to_pixbuf_at_size (dev, thumb, -1, -1);
+        pixbuf = itdb_thumb_to_pixbuf_at_size (device, thumb, -1, -1);
         pixbufs = g_list_append (pixbufs, pixbuf);
         break;
     case ITDB_THUMB_TYPE_INVALID:
@@ -564,14 +574,14 @@ GList *itdb_thumb_to_pixbufs (Itdb_Device *dev, Itdb_Thumb *thumb)
     return pixbufs;
 }
 #else
-gpointer itdb_thumb_to_pixbuf_at_size (Itdb_Device *dev, Itdb_Thumb *thumb, 
+gpointer itdb_thumb_to_pixbuf_at_size (Itdb_Device *device, Itdb_Thumb *thumb,
                                        gint width, gint height)
 {
     return NULL;
 }
 
 
-GList *itdb_thumb_to_pixbufs (Itdb_Device *dev, Itdb_Thumb *thumb) 
+GList *itdb_thumb_to_pixbufs (Itdb_Device *device, Itdb_Thumb *thumb)
 {
     return NULL;
 }
diff --git a/src/itdb_thumb.h b/src/itdb_thumb.h
index 7c2806c..9170945 100644
--- a/src/itdb_thumb.h
+++ b/src/itdb_thumb.h
@@ -27,14 +27,13 @@
 #include "itdb_device.h"
 
 /* Types of thumbnails in Itdb_Image */
-enum _ItdbThumbDataType {
+typedef enum {
     ITDB_THUMB_TYPE_INVALID,
     ITDB_THUMB_TYPE_FILE,
     ITDB_THUMB_TYPE_MEMORY,
     ITDB_THUMB_TYPE_PIXBUF,
     ITDB_THUMB_TYPE_IPOD
-};
-typedef enum _ItdbThumbDataType ItdbThumbDataType;
+} ItdbThumbDataType;
 
 /* The Itdb_Thumb structure can represent two slightly different
    thumbnails:
@@ -51,11 +50,22 @@ typedef enum _ItdbThumbDataType ItdbThumbDataType;
 
      filename point to a 'real' image file OR image_data and
      image_data_len are set.
- 
+
   b) a thumbnail (big or small) stored on a database in the iPod.  In
      these cases, id corresponds to the ID originally used in the
      database, filename points to a .ithmb file on the iPod
  */
+
+/**
+ * Itdb_Thumb:
+ * @data_type: The type of data (file, memory, pixbuf, ipod, etc.)
+ * @rotation:  Angle by which the image is rotated counterclockwise
+ *
+ * This is an opaque structure representing a thumbnail to be
+ * transferred to the ipod or read from the ipod.
+ *
+ * Since: 0.3.0
+ */
 struct _Itdb_Thumb {
     ItdbThumbDataType data_type;
     guint rotation;
diff --git a/src/itdb_track.c b/src/itdb_track.c
index dbe427e..16a07d8 100644
--- a/src/itdb_track.c
+++ b/src/itdb_track.c
@@ -38,9 +38,9 @@
  *
  * Creates an empty #Itdb_Track
  *
- * Return Value: the new #Itdb_Track, free it with itdb_track_free() when no
+ * Returns: the new #Itdb_Track, free it with itdb_track_free() when no
  * longer needed
- **/
+ */
 Itdb_Track *itdb_track_new (void)
 {
     Itdb_Track *track = g_new0 (Itdb_Track, 1);
@@ -195,15 +195,15 @@ static void itdb_track_set_defaults (Itdb_Track *tr)
 
 /**
  * itdb_track_add:
- * @itdb: an #Itdb_iTunesDB
- * @track: an #Itdb_Track
- * @pos: position of the track to add
+ * @itdb:   an #Itdb_iTunesDB
+ * @track:  an #Itdb_Track
+ * @pos:    position of the track to add
  *
  * Adds @track to @itdb->tracks at position @pos (or at the end if pos
  * is -1). The application is responsible to also add it to the master
  * playlist. The @itdb gets ownership of the @track and will take care of
  * freeing the memory it uses when it's no longer necessary.
- **/
+ */
 void itdb_track_add (Itdb_iTunesDB *itdb, Itdb_Track *track, gint32 pos)
 {
     g_return_if_fail (itdb);
@@ -222,7 +222,7 @@ void itdb_track_add (Itdb_iTunesDB *itdb, Itdb_Track *track, gint32 pos)
  * @track: an #Itdb_Track
  *
  * Frees the memory used by @track
- **/
+ */
 void itdb_track_free (Itdb_Track *track)
 {
     g_return_if_fail (track);
@@ -270,7 +270,7 @@ void itdb_track_free (Itdb_Track *track)
  * Removes @track from the #Itdb_iTunesDB it's associated with, and frees the
  * memory it uses. It doesn't remove the track from the playlists it may have
  * been added to, in particular it won't be removed from the master playlist.
- **/
+ */
 void itdb_track_remove (Itdb_Track *track)
 {
     Itdb_iTunesDB *itdb;
@@ -290,8 +290,8 @@ void itdb_track_remove (Itdb_Track *track)
  * Removes @track from the #Itdb_iTunesDB it's associated with, but do not free
  * memory. It doesn't remove the track from the playlists it may have been
  * added to, in particular it won't be removed from the master playlist.
- * track->itdb is set to NULL.
- **/
+ * @track->itdb is set to NULL.
+ */
 void itdb_track_unlink (Itdb_Track *track)
 {
     Itdb_iTunesDB *itdb;
@@ -310,8 +310,8 @@ void itdb_track_unlink (Itdb_Track *track)
  *
  * Duplicates an existing track
  *
- * Return value: a newly allocated #Itdb_Track
- **/
+ * Returns: a newly allocated #Itdb_Track
+ */
 Itdb_Track *itdb_track_duplicate (Itdb_Track *tr)
 {
     Itdb_Track *tr_dup;
@@ -431,16 +431,18 @@ static gboolean itdb_track_set_thumbnails_internal (Itdb_Track *track,
 
 /**
  * itdb_track_set_thumbnails:
- * @track: an #Itdb_Track
+ * @track:    an #Itdb_Track
  * @filename: image file to use as a thumbnail
  *
  * Uses the image contained in @filename to generate iPod thumbnails. The image
  * can be in any format supported by gdk-pixbuf. To save memory, the thumbnails
- * will only be generated when necessary, ie when itdb_save() or a similar
+ * will only be generated when necessary, i.e. when itdb_save() or a similar
  * function is called.
  *
- * Return value: TRUE if the thumbnail could be added, FALSE otherwise.
- **/
+ * Returns: TRUE if the thumbnail could be added, FALSE otherwise.
+ *
+ * Since: 0.3.0
+ */
 gboolean itdb_track_set_thumbnails (Itdb_Track *track,
 				    const gchar *filename)
 {
@@ -453,18 +455,20 @@ gboolean itdb_track_set_thumbnails (Itdb_Track *track,
 
 /**
  * itdb_track_set_thumbnails_from_data:
- * @track: an #Itdb_Track
- * @image_data: data used to create the thumbnail (the raw contents of
- *              an image file)
+ * @track:          an #Itdb_Track
+ * @image_data:     data used to create the thumbnail (the raw contents of
+ *                  an image file)
  * @image_data_len: length of above data block
  *
  * Uses @image_data to generate iPod thumbnails. The image can be in
  * any format supported by gdk-pixbuf. To save memory, the thumbnails
- * will only be generated when necessary, ie when itdb_save() or a
+ * will only be generated when necessary, i.e. when itdb_save() or a
  * similar function is called.
  *
- * Return value: TRUE if the thumbnail could be added, FALSE otherwise.
- **/
+ * Returns: TRUE if the thumbnail could be added, FALSE otherwise.
+ *
+ * Since: 0.4.0
+ */
 gboolean itdb_track_set_thumbnails_from_data (Itdb_Track *track,
 					      const guchar *image_data,
 					      gsize image_data_len)
@@ -479,15 +483,17 @@ gboolean itdb_track_set_thumbnails_from_data (Itdb_Track *track,
 
 /**
  * itdb_track_set_thumbnails_from_pixbuf:
- * @track: an #Itdb_Track
+ * @track:  an #Itdb_Track
  * @pixbuf: a #GdkPixbuf used to generate the thumbnail
  *
  * Uses @pixbuf to generate iPod thumbnails. To save memory, the thumbnails
- * will only be generated when necessary, ie when itdb_save() or a
+ * will only be generated when necessary, i.e. when itdb_save() or a
  * similar function is called.
  *
- * Return value: TRUE if the thumbnail could be added, FALSE otherwise.
- **/
+ * Returns: TRUE if the thumbnail could be added, FALSE otherwise.
+ *
+ * Since: 0.5.0
+ */
 gboolean itdb_track_set_thumbnails_from_pixbuf (Itdb_Track *track,
                                                 gpointer pixbuf)
 {
@@ -503,7 +509,9 @@ gboolean itdb_track_set_thumbnails_from_pixbuf (Itdb_Track *track,
  * @track: an #Itdb_Track
  *
  * Removes the thumbnails associated with @track
- **/
+ *
+ * Since: 0.3.0
+ */
 void itdb_track_remove_thumbnails (Itdb_Track *track)
 {
     g_return_if_fail (track);
@@ -518,20 +526,23 @@ void itdb_track_remove_thumbnails (Itdb_Track *track)
 /**
  * itdb_track_by_id:
  * @itdb: an #Itdb_iTunesDB
- * @id: ID of the track to look for
+ * @id:   ID of the track to look for
  *
  * Looks up a track using its ID in @itdb.
+ *
  * Looking up tracks by ID is not really a good idea because the IDs
  * are created by itdb just before export. The functions are here
  * because they are needed during import of the iTunesDB which is
  * referencing tracks by IDs.
- * This function is very slow (linear in the number of tracks contained in the
- * database). If you need to lookup many IDs use itdb_track_id_tree_create(),
- * itdb_track_id_tree_destroy(), and itdb_track_id_tree_by_id().
  *
- * Return value: #Itdb_Track with the ID @id or NULL if the ID cannot be
+ * This function is very slow (linear in the number of tracks
+ * contained in the database). If you need to lookup many IDs use
+ * itdb_track_id_tree_create(), itdb_track_id_tree_destroy(), and
+ * itdb_track_id_tree_by_id().
+ *
+ * Returns: #Itdb_Track with the ID @id or NULL if the ID cannot be
  * found.
- **/
+ */
 Itdb_Track *itdb_track_by_id (Itdb_iTunesDB *itdb, guint32 id)
 {
     GList *gl;
@@ -560,11 +571,11 @@ static gint track_id_compare (gconstpointer a, gconstpointer b)
  * @itdb: an #Itdb_iTunesDB
  *
  * Creates a balanced-binary tree for quick ID lookup that is used in
- * itdb_track_by_id_tree() function below
+ * itdb_track_by_id_tree()
  *
- * Return value: a #GTree indexed by track IDs to be freed with
+ * Returns: a #GTree indexed by track IDs to be freed with
  * itdb_track_id_tree_destroy() when no longer used
- **/
+ */
 GTree *itdb_track_id_tree_create (Itdb_iTunesDB *itdb)
 {
     GTree *idtree;
@@ -588,7 +599,7 @@ GTree *itdb_track_id_tree_create (Itdb_iTunesDB *itdb)
  * @idtree: a #GTree
  *
  * Frees the memory used by @idtree
- **/
+ */
 void itdb_track_id_tree_destroy (GTree *idtree)
 {
     g_return_if_fail (idtree);
@@ -599,14 +610,14 @@ void itdb_track_id_tree_destroy (GTree *idtree)
 /**
  * itdb_track_id_tree_by_id:
  * @idtree: a #GTree created using itdb_track_id_tree_create()
- * @id: the ID of the track to search for
+ * @id:     the ID of the track to search for
  *
- * Lookup an #Itdb_Track by @id using @idtree for faster lookup (compared to
- * itdb_track_by_id)
+ * Lookup an #Itdb_Track by @id using @idtree for faster lookup
+ * (compared to itdb_track_by_id())
  *
- * Return value: the #Itdb_Track whose ID is @id, or NULL if such a track
+ * Returns: the #Itdb_Track whose ID is @id, or NULL if such a track
  * couldn't be found
- **/
+ */
 Itdb_Track *itdb_track_id_tree_by_id (GTree *idtree, guint32 id)
 {
     g_return_val_if_fail (idtree, NULL);
@@ -618,8 +629,12 @@ Itdb_Track *itdb_track_id_tree_by_id (GTree *idtree, guint32 id)
  * itdb_track_has_thumbnails:
  * @track: an #Itdb_Track
  *
- * Return value: TRUE if @track has artwork available, FALSE otherwise
- **/
+ * Determine if a @track has thumbnails
+ *
+ * Returns: TRUE if @track has artwork available, FALSE otherwise
+ *
+ * Since: 0.7.0
+ */
 gboolean itdb_track_has_thumbnails (Itdb_Track *track)
 {
     g_return_val_if_fail (track != NULL, FALSE);
@@ -628,20 +643,22 @@ gboolean itdb_track_has_thumbnails (Itdb_Track *track)
 
 /**
  * itdb_track_get_thumbnail:
- * @track: an #Itdb_Track
- * @width: width of the pixbuf to retrieve, -1 for the biggest possible size
- * (with no scaling)
+ * @track:  an #Itdb_Track
+ * @width:  width of the pixbuf to retrieve, -1 for the biggest possible size
+ *          (with no scaling)
  * @height: height of the pixbuf to retrieve, -1 for the biggest possible size
- * (with no scaling)
+ *          (with no scaling)
  *
- * Returns a #GdkPixbuf representing the cover associated with the current
- * track, scaling it if appropriate. If either height or width is -1, then the 
- * biggest unscaled thumbnail available will be returned
+ * Get a thumbnail representing the cover associated with the current track,
+ * scaling it if appropriate. If either height or width is -1, then the biggest
+ * unscaled thumbnail available will be returned.
  *
- * Return value: a #GdkPixbuf that must be unreffed when no longer used, NULL
+ * Returns: a #GdkPixbuf that must be unreffed when no longer used, NULL
  * if no artwork could be found or if libgpod is compiled without GdkPixbuf
  * support
- **/
+ *
+ * Since: 0.7.0
+ */
 gpointer itdb_track_get_thumbnail (Itdb_Track *track, gint width, gint height)
 {
     g_return_val_if_fail (track != NULL, NULL);
diff --git a/src/ithumb-writer.c b/src/ithumb-writer.c
index c29151e..9fbe9c6 100644
--- a/src/ithumb-writer.c
+++ b/src/ithumb-writer.c
@@ -1391,7 +1391,7 @@ static gboolean ithumb_rearrange_thumbnail_file (gpointer _key,
 
    If a thumbnail has been removed, a slot in the file is opened. This
    slot is filled by copying data from the end of the file and
-   adjusting the corresponding Itdb_Image offset pointer. When all
+   adjusting the corresponding Itdb_Thumb offset pointer. When all
    slots are filled, the file is truncated to the new length.
 */
 static gboolean