Documentation: minor updates and formatting changes

1 files changed, 23 insertions, 20 deletions

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);