Documentation: minor updates and formatting changes

10 files changed, 409 insertions, 381 deletions

diff --git a/src/itdb_artwork.c b/src/itdb_artwork.c
index 8b8c6db..0258b45 100644
--- a/src/itdb_artwork.c
+++ b/src/itdb_artwork.c
@@ -136,8 +136,8 @@ itdb_artwork_remove_thumbnails (Itdb_Artwork *artwork)
  * 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
  * otherwise. @error is set appropriately.
@@ -196,8 +196,8 @@ itdb_artwork_set_thumbnail (Itdb_Artwork *artwork,
  * 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
  * otherwise. @error is set appropriately.
@@ -257,8 +257,8 @@ itdb_artwork_set_thumbnail_from_pixbuf (Itdb_Artwork *artwork,
  * @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
  * otherwise. @error is set appropriately.
diff --git a/src/itdb_device.c b/src/itdb_device.c
index 64817c8..1b47018 100644
--- a/src/itdb_device.c
+++ b/src/itdb_device.c
@@ -1169,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
+ * Return value: 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)
@@ -1700,7 +1698,7 @@ G_GNUC_INTERNAL gboolean itdb_device_requires_checksum (Itdb_Device *device)
  * Return the storage info for this iPod
  *
  * Return value: 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 f5774e6..1ff1856 100644
--- a/src/itdb_device.h
+++ b/src/itdb_device.h
@@ -84,7 +84,7 @@ enum _ItdbThumbFormat
  *                      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)
+ *                      otherwise.  (see itdb_set_sysinfo())
  * @timezone_shift:     The difference in seconds between the current timezone
  *                      and UTC
  *
diff --git a/src/itdb_itunesdb.c b/src/itdb_itunesdb.c
index 91e17f8..f9f75c6 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->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.
- **/
+ */
 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)
@@ -1174,7 +1174,7 @@ void itdb_free (Itdb_iTunesDB *itdb)
  * FIXME: not implemented yet 
  *
  * Return value: always return NULL since it's unimplemented
- **/
+ */
 Itdb_iTunesDB *itdb_duplicate (Itdb_iTunesDB *itdb)
 {
     g_return_val_if_fail (itdb, NULL);
@@ -1190,7 +1190,7 @@ Itdb_iTunesDB *itdb_duplicate (Itdb_iTunesDB *itdb)
  *
  * Return value: the number of playlists in @itdb (including the master 
  * playlist)
- **/
+ */
 guint32 itdb_playlists_number (Itdb_iTunesDB *itdb)
 {
     g_return_val_if_fail (itdb, 0);
@@ -1205,7 +1205,7 @@ guint32 itdb_playlists_number (Itdb_iTunesDB *itdb)
  * Counts the number of tracks stored in @itdb
  *
  * Return value: the number of tracks in @itdb
- **/
+ */
 guint32 itdb_tracks_number (Itdb_iTunesDB *itdb)
 {
     g_return_val_if_fail (itdb, 0);
@@ -1222,7 +1222,7 @@ guint32 itdb_tracks_number (Itdb_iTunesDB *itdb)
  * Return value: 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;
@@ -1246,7 +1246,7 @@ guint32 itdb_tracks_number_nontransferred (Itdb_iTunesDB *itdb)
  *
  * Return value: 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,8 +2956,8 @@ 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
  *
@@ -2965,7 +2965,7 @@ itdb_parse_internal (Itdb_iTunesDB *itdb, GError **error)
  * 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,8 +3043,8 @@ 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.
  *
@@ -3052,7 +3052,7 @@ Itdb_iTunesDB *itdb_parse (const gchar *mp, GError **error)
  * 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->filename.
+ * to write to @itdb->filename.
  *
  * Return value: 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
@@ -5222,7 +5222,7 @@ gboolean itdb_write_file (Itdb_iTunesDB *itdb, const gchar *filename,
  *
  * Return value: 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.
+ *
+ * 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
  * 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
  * set accordingly.
- **/
+ */
 gboolean itdb_shuffle_write_file (Itdb_iTunesDB *itdb,
 				  const gchar *filename, GError **error)
 {
@@ -5568,8 +5567,8 @@ 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
@@ -5577,7 +5576,7 @@ gboolean itdb_shuffle_write_file (Itdb_iTunesDB *itdb,
  * copy the file from there to the iPod.
  *
  * Return value: 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,13 +5692,13 @@ 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
  */
@@ -5718,8 +5717,8 @@ 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
+ * Return value: the @itdb mountpoint, this string shouldn't be freed
+ * nor modified
  *
  * Since: 0.4.0
  */
@@ -5744,9 +5743,9 @@ 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.
  *
  * Return value: max number of directories in iPod_Control/Music
  *
@@ -5762,26 +5761,26 @@ 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
+ * Return value: 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.
  *
@@ -5920,26 +5919,37 @@ 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
  * 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.
@@ -6047,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.
@@ -6058,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
  * set accordingly.
- **/
+ */
 gboolean itdb_cp_track_to_ipod (Itdb_Track *track,
 				const gchar *filename, GError **error)
 {
@@ -6110,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
  * filename is set in @track. Must be freed with g_free() after use.
- **/
+ */
 gchar *itdb_filename_on_ipod (Itdb_Track *track)
 {
     gchar *result = NULL;
@@ -6160,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
  * set accordingly.
- **/
+ */
 gboolean itdb_cp (const gchar *from_file, const gchar *to_file,
 		  GError **error)
 {
@@ -6357,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()
  * after use.
- **/
+ */
 static gchar *itdb_get_dir (const gchar *mountpoint, const gchar *dir)
 {
     gchar *control_dir;
@@ -6386,12 +6400,12 @@ 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 
+ * Return value: path to the @file or NULL if non-existent. Must g_free()
  * after use.
  *
  * Since: 0.4.0
@@ -6435,7 +6449,7 @@ gchar *itdb_get_itunes_dir (const gchar *mountpoint)
  *
  * Return value: 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);
@@ -6582,7 +6596,7 @@ gchar *itdb_get_artworkdb_path (const gchar *mountpoint)
  *
  * 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;
@@ -6602,7 +6616,7 @@ time_t itdb_time_get_mac_time (void)
  *
  * 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;
@@ -6618,7 +6632,7 @@ time_t itdb_time_mac_to_host (time_t time)
  *
  * 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;
diff --git a/src/itdb_photoalbum.c b/src/itdb_photoalbum.c
index cf6238e..04e29cd 100644
--- a/src/itdb_photoalbum.c
+++ b/src/itdb_photoalbum.c
@@ -207,8 +207,8 @@ 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.
  *
@@ -472,21 +472,21 @@ 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.
  *
@@ -507,23 +507,23 @@ 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.
  *
@@ -546,21 +546,21 @@ 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.
  *
  * Return value: a pointer to the added photo.
  *
@@ -581,19 +581,21 @@ 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.
- *
- * 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.
- *
+ * @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.
+ *
+ * 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
  */
@@ -629,9 +631,9 @@ 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.
@@ -660,16 +662,18 @@ 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
  */
@@ -701,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
@@ -729,10 +734,10 @@ 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.
  *
@@ -760,8 +765,8 @@ 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.
  *
diff --git a/src/itdb_playlist.c b/src/itdb_playlist.c
index f44a7e0..63d7f23 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. 
- **/
+ * Return value: 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, ...)
- **/
+ * Return value: 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);
@@ -142,7 +142,7 @@ 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
- **/
+ */
 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.
- **/
+ */
 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,8 +930,8 @@ 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
  */
@@ -949,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;
@@ -1007,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)
@@ -1022,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);
@@ -1036,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);
@@ -1060,7 +1061,7 @@ void itdb_splr_add (Itdb_Playlist *pl, Itdb_SPLRule *splr, gint pos)
  *
  * Return value: 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);
@@ -1079,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
- **/
+ * 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
+ */
 Itdb_SPLRule *itdb_splr_add_new (Itdb_Playlist *pl, gint pos)
 {
     Itdb_SPLRule *splr;
@@ -1118,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. 
- **/
+ * Return value: 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;
@@ -1168,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;
@@ -1204,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
+ *
+ * Return value: 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);
@@ -1246,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);
@@ -1262,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);
@@ -1309,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;
@@ -1332,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;
@@ -1349,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;
@@ -1366,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 
- **/
+ * Return value: 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);
@@ -1384,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)
 {
@@ -1405,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);
@@ -1427,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.
- **/
+ * Return value: 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;
@@ -1451,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
- **/
+ * Return value: 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;
@@ -1469,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
- **/
+ * Return value: 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;
@@ -1564,7 +1568,7 @@ void itdb_playlist_set_podcasts (Itdb_Playlist *pl)
  * Gets the master playlist of @itdb
  *
  * Return value: the master playlist of @itdb
- **/
+ */
 Itdb_Playlist *itdb_playlist_mpl (Itdb_iTunesDB *itdb)
 {
     Itdb_Playlist *pl;
@@ -1580,14 +1584,14 @@ 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
+ * Return value: the podcasts playlist of @itdb, or NULL if there is
+ * not one
  *
  * Since: 0.1.6
  */
@@ -1610,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
  *
- * Checks if @track is in @pl.
- * 
  * Return value: 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);
@@ -1634,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
- **/
+ * Return value: the number of playlist containing @track
+ */
 guint32 itdb_playlist_contain_track_number (Itdb_Track *tr)
 {
     Itdb_iTunesDB *itdb;
@@ -1666,8 +1670,8 @@ guint32 itdb_playlist_contain_track_number (Itdb_Track *tr)
  *
  * Counts the number of tracks in @pl
  *
- * Return value: track count
- **/
+ * Return value: 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 0199c68..63a3671 100644
--- a/src/itdb_thumb.c
+++ b/src/itdb_thumb.c
@@ -312,7 +312,7 @@ Itdb_Thumb_Ipod_Item *itdb_thumb_ipod_get_item_by_type (Itdb_Thumb *thumbs,
  *
  * Return value: 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;
@@ -367,9 +367,12 @@ const GList *itdb_thumb_ipod_get_thumbs (Itdb_Thumb_Ipod *thumbs)
  *          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>
  *
  * Return value: a #GdkPixbuf that must be unreffed with gdk_pixbuf_unref()
  * after use, or NULL if the creation of the gdk-pixbuf failed or if
diff --git a/src/itdb_track.c b/src/itdb_track.c
index 510fc2f..cbfc2ce 100644
--- a/src/itdb_track.c
+++ b/src/itdb_track.c
@@ -40,7 +40,7 @@
  *
  * Return Value: 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);
@@ -203,7 +203,7 @@ static void itdb_track_set_defaults (Itdb_Track *tr)
  * 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;
@@ -311,7 +311,7 @@ void itdb_track_unlink (Itdb_Track *track)
  * Duplicates an existing track
  *
  * Return value: a newly allocated #Itdb_Track
- **/
+ */
 Itdb_Track *itdb_track_duplicate (Itdb_Track *tr)
 {
     Itdb_Track *tr_dup;
@@ -436,7 +436,7 @@ static gboolean itdb_track_set_thumbnails_internal (Itdb_Track *track,
  *
  * 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.
@@ -462,7 +462,7 @@ gboolean itdb_track_set_thumbnails (Itdb_Track *track,
  *
  * 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.
@@ -487,7 +487,7 @@ gboolean itdb_track_set_thumbnails_from_data (Itdb_Track *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.
@@ -529,17 +529,20 @@ void itdb_track_remove_thumbnails (Itdb_Track *track)
  * @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().
+ *
+ * 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
  * found.
- **/
+ */
 Itdb_Track *itdb_track_by_id (Itdb_iTunesDB *itdb, guint32 id)
 {
     GList *gl;
@@ -568,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
  * itdb_track_id_tree_destroy() when no longer used
- **/
+ */
 GTree *itdb_track_id_tree_create (Itdb_iTunesDB *itdb)
 {
     GTree *idtree;
@@ -596,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);
@@ -609,12 +612,12 @@ void itdb_track_id_tree_destroy (GTree *idtree)
  * @idtree: a #GTree created using itdb_track_id_tree_create()
  * @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
  * couldn't be found
- **/
+ */
 Itdb_Track *itdb_track_id_tree_by_id (GTree *idtree, guint32 id)
 {
     g_return_val_if_fail (idtree, NULL);