From 3b8943d3e82d145950d100a5b6e2c1b9805bd073 Mon Sep 17 00:00:00 2001
From: Todd Zullinger <tmz@pobox.com>
Date: Thu, 7 Aug 2008 13:23:06 -0400
Subject: Documentation: use "Returns:" consistently in gtk-doc comments

---
 src/itdb_artwork.c     | 12 ++++-----
 src/itdb_chapterdata.c | 10 ++++----
 src/itdb_device.c      | 28 ++++++++++-----------
 src/itdb_itunesdb.c    | 68 +++++++++++++++++++++++++-------------------------
 src/itdb_photoalbum.c  | 22 ++++++++--------
 src/itdb_playlist.c    | 38 ++++++++++++++--------------
 src/itdb_thumb.c       |  8 +++---
 src/itdb_track.c       | 20 +++++++--------
 8 files changed, 103 insertions(+), 103 deletions(-)

diff --git a/src/itdb_artwork.c b/src/itdb_artwork.c
index 0258b45..dd6c4ca 100644
--- a/src/itdb_artwork.c
+++ b/src/itdb_artwork.c
@@ -48,7 +48,7 @@
  *
  * 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
@@ -82,7 +82,7 @@ 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
  */
@@ -139,7 +139,7 @@ itdb_artwork_remove_thumbnails (Itdb_Artwork *artwork)
  * %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
@@ -199,7 +199,7 @@ itdb_artwork_set_thumbnail (Itdb_Artwork *artwork,
  * %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
@@ -260,7 +260,7 @@ itdb_artwork_set_thumbnail_from_pixbuf (Itdb_Artwork *artwork,
  * %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
@@ -905,7 +905,7 @@ gpointer itdb_thumb_ipod_item_to_pixbuf (Itdb_Device *device,
  * 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
  *
diff --git a/src/itdb_chapterdata.c b/src/itdb_chapterdata.c
index 99058c7..c74e6d6 100644
--- a/src/itdb_chapterdata.c
+++ b/src/itdb_chapterdata.c
@@ -41,7 +41,7 @@
  *
  * Creates a new #Itdb_Chapterdata
  *
- * Return value: a new #Itdb_Chapterdata to be freed with
+ * Returns: a new #Itdb_Chapterdata to be freed with
  *               itdb_chapterdata_free() when no longer needed
  *
  * Since: 0.7.0
@@ -96,7 +96,7 @@ 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
  */
@@ -164,7 +164,7 @@ 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
@@ -197,7 +197,7 @@ 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
@@ -223,7 +223,7 @@ Itdb_Chapter *itdb_chapter_duplicate (Itdb_Chapter *chapter)
  *
  * 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
diff --git a/src/itdb_device.c b/src/itdb_device.c
index 1b47018..b035c30 100644
--- a/src/itdb_device.c
+++ b/src/itdb_device.c
@@ -649,7 +649,7 @@ 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
@@ -759,7 +759,7 @@ 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
  */
@@ -840,7 +840,7 @@ static void write_sysinfo_entry (const gchar *key,
  * 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
  */
@@ -897,7 +897,7 @@ gboolean itdb_device_write_sysinfo (Itdb_Device *device, GError **error)
  *
  * 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
@@ -948,7 +948,7 @@ 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
  */
@@ -1176,7 +1176,7 @@ itdb_device_musicdirs_number (Itdb_Device *device)
  *
  * Check if endianess can be determined by looking at header of @path.
  *
- * 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)
@@ -1286,7 +1286,7 @@ 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
  */
@@ -1302,7 +1302,7 @@ 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
@@ -1329,7 +1329,7 @@ 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
@@ -1358,7 +1358,7 @@ 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
  */
@@ -1380,7 +1380,7 @@ 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
  */
@@ -1428,7 +1428,7 @@ 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
  */
@@ -1622,7 +1622,7 @@ 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
  */
@@ -1697,7 +1697,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
+ * Returns: TRUE if storage info could be obtained, FALSE otherwise
  */
 gboolean itdb_device_get_storage_info (Itdb_Device *device, guint64 *capacity, guint64 *free)
 {
diff --git a/src/itdb_itunesdb.c b/src/itdb_itunesdb.c
index f9f75c6..66f024d 100644
--- a/src/itdb_itunesdb.c
+++ b/src/itdb_itunesdb.c
@@ -359,7 +359,7 @@ static void fcontents_free (FContents *cts)
  * 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)
@@ -1173,7 +1173,7 @@ 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)
 {
@@ -1188,7 +1188,7 @@ 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)
@@ -1204,7 +1204,7 @@ 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)
 {
@@ -1219,7 +1219,7 @@ 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)
  */
@@ -1244,7 +1244,7 @@ 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)
@@ -2961,7 +2961,7 @@ itdb_parse_internal (Itdb_iTunesDB *itdb, GError **error)
  *
  * 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
@@ -3048,7 +3048,7 @@ Itdb_iTunesDB *itdb_parse (const gchar *mp, GError **error)
  *
  *  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
@@ -5123,7 +5123,7 @@ static gboolean write_db_checksum (FExport *fexp, GError **error)
  * Write the content of @itdb to @filename. If @filename is NULL, it attempts
  * 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)
@@ -5220,7 +5220,7 @@ 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)
@@ -5387,7 +5387,7 @@ All integers in the iTunesSD file are in BIG endian form...
  * 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
+ * Returns: TRUE on success, FALSE on error, in which case @error is
  * set accordingly.
  */
 gboolean itdb_shuffle_write (Itdb_iTunesDB *itdb, GError **error)
@@ -5450,7 +5450,7 @@ static gboolean haystack (gchar *filetype, gchar **desclist)
  *
  * 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,
@@ -5575,7 +5575,7 @@ gboolean itdb_shuffle_write_file (Itdb_iTunesDB *itdb,
  * 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)
 {
@@ -5717,7 +5717,7 @@ 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
+ * Returns: the @itdb mountpoint, this string shouldn't be freed
  * nor modified
  *
  * Since: 0.4.0
@@ -5747,7 +5747,7 @@ const gchar *itdb_photodb_get_mountpoint (Itdb_PhotoDB *photodb)
  * determined number. Otherwise count the directories first and set
  * @itdb->musicdirs.
  *
- * Return value: max number of directories in iPod_Control/Music
+ * Returns: max number of directories in iPod_Control/Music
  *
  * Since: 0.1.3
  */
@@ -5779,7 +5779,7 @@ gint itdb_musicdirs_number (Itdb_iTunesDB *itdb)
  * itdb_cp_finalize() to obtain relevant update information for
  * #Itdb_Track.
  *
- * Return value: a valid filename on the iPod where @filename can be
+ * 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.
@@ -5947,7 +5947,7 @@ gchar *itdb_cp_get_dest_filename (Itdb_Track *track,
  *   </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
  * no longer used. If an error occurs NULL is returned and @error is
@@ -6083,7 +6083,7 @@ Itdb_Track *itdb_cp_finalize (Itdb_Track *track,
  *
  * @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,
@@ -6133,7 +6133,7 @@ gboolean itdb_cp_track_to_ipod (Itdb_Track *track,
  * 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)
@@ -6180,7 +6180,7 @@ gchar *itdb_filename_on_ipod (Itdb_Track *track)
  *
  * 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,
@@ -6343,7 +6343,7 @@ 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
@@ -6376,7 +6376,7 @@ gchar *itdb_get_control_dir (const gchar *mountpoint)
  * 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)
@@ -6405,7 +6405,7 @@ static gchar *itdb_get_dir (const gchar *mountpoint, const gchar *dir)
  *
  * Retrieve a path to the @file in @dir
  *
- * Return value: path to the @file or NULL if non-existent. Must g_free()
+ * Returns: path to the @file or NULL if non-existent. Must g_free()
  * after use.
  *
  * Since: 0.4.0
@@ -6428,7 +6428,7 @@ 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
@@ -6447,7 +6447,7 @@ 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)
@@ -6464,7 +6464,7 @@ 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
@@ -6483,7 +6483,7 @@ 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
@@ -6501,7 +6501,7 @@ 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
@@ -6529,7 +6529,7 @@ 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
@@ -6557,7 +6557,7 @@ 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
@@ -6592,7 +6592,7 @@ 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
@@ -6612,7 +6612,7 @@ 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
@@ -6628,7 +6628,7 @@ 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
@@ -6651,7 +6651,7 @@ 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
  */
diff --git a/src/itdb_photoalbum.c b/src/itdb_photoalbum.c
index 04e29cd..84febf7 100644
--- a/src/itdb_photoalbum.c
+++ b/src/itdb_photoalbum.c
@@ -121,7 +121,7 @@ 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
@@ -151,7 +151,7 @@ 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
@@ -180,7 +180,7 @@ 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
@@ -212,7 +212,7 @@ gchar *itdb_get_photos_thumb_dir (const gchar *mountpoint)
  *
  * 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
  */
@@ -252,7 +252,7 @@ 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.
  *
@@ -488,7 +488,7 @@ static Itdb_Artwork *itdb_photodb_add_photo_internal (Itdb_PhotoDB *db,
  * %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
  */
@@ -525,7 +525,7 @@ Itdb_Artwork *itdb_photodb_add_photo (Itdb_PhotoDB *db,
  * %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
  */
@@ -562,7 +562,7 @@ Itdb_Artwork *itdb_photodb_add_photo_from_data (Itdb_PhotoDB *db,
  * %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.5.0
  */
@@ -638,7 +638,7 @@ void itdb_photodb_remove_photo (Itdb_PhotoDB *db,
  * 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
@@ -741,7 +741,7 @@ void itdb_photodb_photoalbum_add_photo (Itdb_PhotoDB *db,
  *
  * 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
  */
@@ -772,7 +772,7 @@ Itdb_PhotoAlbum *itdb_photodb_photoalbum_create (Itdb_PhotoDB *db,
  *
  * 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
diff --git a/src/itdb_playlist.c b/src/itdb_playlist.c
index 63d7f23..e5c9e6b 100644
--- a/src/itdb_playlist.c
+++ b/src/itdb_playlist.c
@@ -43,7 +43,7 @@
  *
  * Checks if @action is a known (to libgpod) smart playlist action.
  *
- * Return value: TRUE if @action is known. Otherwise a warning is
+ * Returns: TRUE if @action is known. Otherwise a warning is
  * displayed and FALSE is returned.
  */
 gboolean itdb_spl_action_known (ItdbSPLAction action)
@@ -86,7 +86,7 @@ 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
+ * Returns: an #Itdb_SPLFieldType corresponding to @splr field
  * type (string, int, date, ...)
  */
 ItdbSPLFieldType itdb_splr_get_field_type (const Itdb_SPLRule *splr)
@@ -141,7 +141,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
+ * Returns: type (range, date, string...) of the action field
  */
 ItdbSPLActionType itdb_splr_get_action_type (const Itdb_SPLRule *splr)
 {
@@ -325,7 +325,7 @@ ItdbSPLActionType itdb_splr_get_action_type (const Itdb_SPLRule *splr)
  *
  * 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)
 {
@@ -1059,7 +1059,7 @@ 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)
@@ -1086,7 +1086,7 @@ Itdb_SPLRule *itdb_splr_new (void)
  * 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
+ * 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
  */
@@ -1125,7 +1125,7 @@ static Itdb_SPLRule *splr_duplicate (Itdb_SPLRule *splr)
  * #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
+ * 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)
@@ -1214,7 +1214,7 @@ void itdb_spl_copy_rules (Itdb_Playlist *dest, Itdb_Playlist *src)
  * 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
+ * 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)
@@ -1375,7 +1375,7 @@ void itdb_playlist_unlink (Itdb_Playlist *pl)
  *
  * Checks if @pl is present in @itdb
  *
- * Return value: TRUE if @pl exists in @itdb, FALSE otherwise
+ * Returns: TRUE if @pl exists in @itdb, FALSE otherwise
  */
 gboolean itdb_playlist_exists (Itdb_iTunesDB *itdb, Itdb_Playlist *pl)
 {
@@ -1435,7 +1435,7 @@ void itdb_playlist_remove_track (Itdb_Playlist *pl, Itdb_Track *track)
  *
  * Looks up a playlist whose ID is @id
  *
- * Return value: the #Itdb_Playlist with ID @id or NULL if there is no
+ * 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)
@@ -1459,7 +1459,7 @@ Itdb_Playlist *itdb_playlist_by_id (Itdb_iTunesDB *itdb, guint64 id)
  *
  * Gets the playlist at the given position in @itdb
  *
- * Return value: the #Itdb_Playlist, or NULL if there is no playlist
+ * Returns: the #Itdb_Playlist, or NULL if there is no playlist
  * at @pos
  */
 Itdb_Playlist *itdb_playlist_by_nr (Itdb_iTunesDB *itdb, guint32 num)
@@ -1478,7 +1478,7 @@ Itdb_Playlist *itdb_playlist_by_nr (Itdb_iTunesDB *itdb, guint32 num)
  *
  * Searches a playlist whose name is @name in @itdb
  *
- * Return value: the first #Itdb_Playlist with name @name, NULL if
+ * 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)
@@ -1503,7 +1503,7 @@ 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
  */
@@ -1520,7 +1520,7 @@ 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
  */
@@ -1567,7 +1567,7 @@ 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)
 {
@@ -1590,7 +1590,7 @@ Itdb_Playlist *itdb_playlist_mpl (Itdb_iTunesDB *itdb)
  *
  * Gets the podcasts playlist of @itdb
  *
- * Return value: the podcasts playlist of @itdb, or NULL if there is
+ * Returns: the podcasts playlist of @itdb, or NULL if there is
  * not one
  *
  * Since: 0.1.6
@@ -1619,7 +1619,7 @@ Itdb_Playlist *itdb_playlist_podcasts (Itdb_iTunesDB *itdb)
  *
  * Checks if @track is in @pl
  *
- * Return value: TRUE if @track is in @pl, FALSE otherwise
+ * Returns: TRUE if @track is in @pl, FALSE otherwise
  */
 gboolean itdb_playlist_contains_track (Itdb_Playlist *pl, Itdb_Track *tr)
 {
@@ -1641,7 +1641,7 @@ gboolean itdb_playlist_contains_track (Itdb_Playlist *pl, Itdb_Track *tr)
  * Counts the number of playlist @track is a member of (not including
  * the master playlist)
  *
- * Return value: the number of playlist containing @track
+ * Returns: the number of playlist containing @track
  */
 guint32 itdb_playlist_contain_track_number (Itdb_Track *tr)
 {
@@ -1670,7 +1670,7 @@ guint32 itdb_playlist_contain_track_number (Itdb_Track *tr)
  *
  * Counts the number of tracks in @pl
  *
- * Return value: the number of tracks in @pl
+ * Returns: the number of tracks in @pl
  */
 guint32 itdb_playlist_tracks_number (Itdb_Playlist *pl)
 {
diff --git a/src/itdb_thumb.c b/src/itdb_thumb.c
index 63a3671..0f9a394 100644
--- a/src/itdb_thumb.c
+++ b/src/itdb_thumb.c
@@ -185,7 +185,7 @@ 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
@@ -310,7 +310,7 @@ Itdb_Thumb_Ipod_Item *itdb_thumb_ipod_get_item_by_type (Itdb_Thumb *thumbs,
  * 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)
@@ -374,7 +374,7 @@ const GList *itdb_thumb_ipod_get_thumbs (Itdb_Thumb_Ipod *thumbs)
  * GDK_PIXBUF() yourself.
  * </note>
  *
- * 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.
  *
@@ -545,7 +545,7 @@ static GList *itdb_thumb_ipod_to_pixbufs (Itdb_Device *device,
  * #GdkPixbuf corresponding to the various thumbnail sizes that were
  * written to the iPod database.
  *
- * Return value: a #GList of #GdkPixbuf which are associated with @thumb, NULL
+ * 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().
diff --git a/src/itdb_track.c b/src/itdb_track.c
index cbfc2ce..16a07d8 100644
--- a/src/itdb_track.c
+++ b/src/itdb_track.c
@@ -38,7 +38,7 @@
  *
  * 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)
@@ -310,7 +310,7 @@ 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)
 {
@@ -439,7 +439,7 @@ static gboolean itdb_track_set_thumbnails_internal (Itdb_Track *track,
  * 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
  */
@@ -465,7 +465,7 @@ gboolean itdb_track_set_thumbnails (Itdb_Track *track,
  * 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
  */
@@ -490,7 +490,7 @@ gboolean itdb_track_set_thumbnails_from_data (Itdb_Track *track,
  * 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
  */
@@ -540,7 +540,7 @@ void itdb_track_remove_thumbnails (Itdb_Track *track)
  * 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
+ * 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)
@@ -573,7 +573,7 @@ static gint track_id_compare (gconstpointer a, gconstpointer b)
  * Creates a balanced-binary tree for quick ID lookup that is used in
  * 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)
@@ -615,7 +615,7 @@ void itdb_track_id_tree_destroy (GTree *idtree)
  * 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)
@@ -631,7 +631,7 @@ Itdb_Track *itdb_track_id_tree_by_id (GTree *idtree, guint32 id)
  *
  * Determine if a @track has thumbnails
  *
- * Return value: TRUE if @track has artwork available, FALSE otherwise
+ * Returns: TRUE if @track has artwork available, FALSE otherwise
  *
  * Since: 0.7.0
  */
@@ -653,7 +653,7 @@ gboolean itdb_track_has_thumbnails (Itdb_Track *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
  *
-- 
cgit