Even more documentation

...and small cleanups.

4 files changed, 57 insertions, 27 deletions

diff --git a/src/main.c b/src/main.c
index c8a91b2..ae0c643 100644
--- a/src/main.c
+++ b/src/main.c
@@ -21,21 +21,28 @@ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
 THE SOFTWARE.
 */
 
-/* main loop, helper functions */
-
-#include <wardrobe.h>
-#include <curl/curl.h>
-#include <libxml/parser.h>
-#include <libxml/tree.h>
+/* system includes */
 #include <stdlib.h>
 #include <string.h>
 #include <stdio.h>
-#include <pthread.h>
 #include <unistd.h>
 #include <poll.h>
-#include <readline/readline.h>
 #include <time.h>
 #include <ctype.h>
+
+/* last.fm scrobbling library */
+#include <wardrobe.h>
+
+#include <curl/curl.h>
+
+#include <libxml/parser.h>
+#include <libxml/tree.h>
+
+#include <pthread.h>
+
+#include <readline/readline.h>
+
+/* pandora.com library */
 #include <piano.h>
 
 #include "player.h"
@@ -58,7 +65,7 @@ int main (int argc, char **argv) {
 	/* needed in main loop */
 	struct pollfd polls = {fileno (stdin), POLLIN, POLLIN};
 	char buf = '\0';
-	BarKeyShortcut_t *curShortcut;
+	BarKeyShortcut_t *curShortcut = NULL;
 
 	BarUiMsg ("Welcome to " PACKAGE "!\n");
 
@@ -131,15 +138,14 @@ int main (int argc, char **argv) {
 	memset (&player, 0, sizeof (player));
 
 	while (!doQuit) {
-		/* already played a song, clean up things/scrobble song */
+		/* song finished playing, clean up things/scrobble song */
 		if (player.mode == PLAYER_FINISHED_PLAYBACK) {
 			scrobbleSong.length = player.songDuration / BAR_PLAYER_MS_TO_S_FACTOR;
 			/* scrobble when >= nn% are played; use seconds, not
 			 * milliseconds */
-			if (scrobbleSong.length > 0 &&
+			if (scrobbleSong.length > 0 && settings.enableScrobbling &&
 					player.songPlayed / BAR_PLAYER_MS_TO_S_FACTOR * 100 /
-					scrobbleSong.length >= settings.lastfmScrobblePercent &&
-					settings.enableScrobbling) {
+					scrobbleSong.length >= settings.lastfmScrobblePercent) {
 				WardrobeReturn_t wRet;
 
 				BarUiMsg ("Scrobbling song... ");
@@ -152,6 +158,8 @@ int main (int argc, char **argv) {
 			}
 			WardrobeSongDestroy (&scrobbleSong);
 			free (player.url);
+			/* FIXME: pthread_join blocks everything if network connection
+			 * is hung up e.g. */
 			pthread_join (playerThread, NULL);
 			memset (&player, 0, sizeof (player));
 		}
@@ -180,6 +188,7 @@ int main (int argc, char **argv) {
 						}
 					}
 				}
+				/* song ready to play */
 				if (curSong != NULL) {
 					PianoStation_t *realStation =
 							PianoFindStationById (ph.stations,
@@ -199,6 +208,7 @@ int main (int argc, char **argv) {
 					scrobbleSong.album = strdup (curSong->album);
 					scrobbleSong.started = time (NULL);
 
+					/* setup player */
 					memset (&player, 0, sizeof (player));
 					player.url = strdup (curSong->audioUrl);
 					player.gain = curSong->fileGain;
@@ -211,7 +221,8 @@ int main (int argc, char **argv) {
 			} /* end if curStation != NULL */
 		}
 
-		/* in the meantime: wait for user actions */
+		/* in the meantime: wait for user actions;
+		 * 1000ms == 1s => refresh time display every second */
 		if (poll (&polls, 1, 1000) > 0) {
 			read (fileno (stdin), &buf, sizeof (buf));
 			curShortcut = settings.keys;
diff --git a/src/player.c b/src/player.c
index 06f3ec3..92038d9 100644
--- a/src/player.c
+++ b/src/player.c
@@ -75,6 +75,12 @@ inline signed short int applyReplayGain (signed short int value,
 	}
 }
 
+/*	Refill player's buffer with dataSize of data
+ *	@param player structure
+ *	@param new data
+ *	@param data size
+ *	@return 1 on success, 0 when buffer overflow occured
+ */
 inline int BarPlayerBufferFill (struct audioPlayer *player, char *data,
 		size_t dataSize) {
 	/* fill buffer */
@@ -89,6 +95,11 @@ inline int BarPlayerBufferFill (struct audioPlayer *player, char *data,
 	return 1;
 }
 
+/*	move data beginning from read pointer to buffer beginning and
+ *	overwrite data already read from buffer
+ *	@param player structure
+ *	@return nothing at all
+ */
 inline void BarPlayerBufferMove (struct audioPlayer *player) {
 	/* move remaining bytes to buffer beginning */
 	memmove (player->buffer, player->buffer + player->bufferRead,
diff --git a/src/settings.c b/src/settings.c
index bc471f0..cd82b7c 100644
--- a/src/settings.c
+++ b/src/settings.c
@@ -59,10 +59,16 @@ void BarGetXdgConfigDir (const char *filename, char *retDir,
 	}
 }
 
+/*	initialize settings structure
+ *	@param settings struct
+ */
 void BarSettingsInit (BarSettings_t *settings) {
 	memset (settings, 0, sizeof (*settings));
 }
 
+/*	free settings structure, zero it afterwards
+ *	@oaram pointer to struct
+ */
 void BarSettingsDestroy (BarSettings_t *settings) {
 	BarKeyShortcut_t *curShortcut = settings->keys, *lastShortcut;
 
@@ -86,6 +92,10 @@ void BarSettingsDestroy (BarSettings_t *settings) {
 	memset (settings, 0, sizeof (*settings));
 }
 
+/*	copy key shortcut into settings structure
+ *	@param shortcut to be copied
+ *	@param destination settings structure
+ */
 void BarSettingsAppendKey (BarKeyShortcut_t *shortcut,
 		BarSettings_t *settings) {
 	BarKeyShortcut_t *tmp = calloc (1, sizeof (*tmp));
@@ -99,6 +109,7 @@ void BarSettingsAppendKey (BarKeyShortcut_t *shortcut,
 		tmp->configKey = strdup (shortcut->configKey);
 	}
 
+	/* insert into linked list */
 	if (settings->keys == NULL) {
 		settings->keys = tmp;
 	} else {
diff --git a/src/ui.c b/src/ui.c
index b9e444d..84fbca1 100644
--- a/src/ui.c
+++ b/src/ui.c
@@ -51,7 +51,7 @@ inline PianoReturn_t BarUiPrintPianoStatus (PianoReturn_t ret) {
 	return ret;
 }
 
-/*	check whether complete string is numeric
+/*	check if all characters of string are numeric
  *	@param the string
  *	@return 1 = yes, 0 = not numeric
  */
@@ -85,10 +85,9 @@ char BarReadlineInt (const char *prompt, int *retVal) {
 	return ret;
 }
 
-/* sort linked list (station); attention: this is a
- * "i-had-no-clue-what-to-do-algo", but it works.
- * @param stations
- * @return NULL-terminated array with sorted stations
+/*	sort linked list (station)
+ *	@param stations
+ *	@return NULL-terminated array with sorted stations
  */
 PianoStation_t **BarSortedStations (PianoStation_t *unsortedStations) {
 	PianoStation_t *currStation, **sortedStations, **currSortedStation;
@@ -148,6 +147,7 @@ PianoStation_t *BarUiSelectStation (PianoHandle_t *ph, const char *prompt) {
 	PianoStation_t **ss = NULL, **ssCurr = NULL, *retStation;
 	int i = 0;
 
+	/* sort and print stations */
 	ss = BarSortedStations (ph->stations);
 	ssCurr = ss;
 	while (*ssCurr != NULL) {
@@ -181,6 +181,7 @@ PianoSong_t *BarUiSelectSong (PianoSong_t *startSong) {
 	PianoSong_t *tmpSong = NULL;
 	int i = 0;
 
+	/* print all songs */
 	tmpSong = startSong;
 	while (tmpSong != NULL) {
 		printf ("%2u) %s - %s\n", i, tmpSong->artist, tmpSong->title);
@@ -206,6 +207,7 @@ PianoArtist_t *BarUiSelectArtist (PianoArtist_t *startArtist) {
 	PianoArtist_t *tmpArtist = NULL;
 	int i = 0;
 
+	/* print all artists */
 	tmpArtist = startArtist;
 	while (tmpArtist != NULL) {
 		printf ("%2u) %s\n", i, tmpArtist->name);
@@ -244,6 +246,7 @@ char *BarUiSelectMusicId (const PianoHandle_t *ph) {
 		}
 		BarUiMsg ("\r");
 		if (searchResult.songs != NULL && searchResult.artists != NULL) {
+			/* songs and artists found */
 			BarUiMsg ("Is this an [a]rtist or [t]rack name? Press c to abort.\n");
 			read (fileno (stdin), &yesnoBuf, sizeof (yesnoBuf));
 			if (yesnoBuf == 'a') {
@@ -256,29 +259,23 @@ char *BarUiSelectMusicId (const PianoHandle_t *ph) {
 				if (tmpSong != NULL) {
 					musicId = strdup (tmpSong->musicId);
 				}
-			} else {
-				BarUiMsg ("Aborted.\n");
 			}
 		} else if (searchResult.songs != NULL) {
+			/* songs found */
 			tmpSong = BarUiSelectSong (searchResult.songs);
 			if (tmpSong != NULL) {
 				musicId = strdup (tmpSong->musicId);
-			} else {
-				BarUiMsg ("Aborted.\n");
 			}
 		} else if (searchResult.artists != NULL) {
+			/* artists found */
 			tmpArtist = BarUiSelectArtist (searchResult.artists);
 			if (tmpArtist != NULL) {
 				musicId = strdup (tmpArtist->musicId);
-			} else {
-				BarUiMsg ("Aborted.\n");
 			}
 		} else {
 			BarUiMsg ("Nothing found...\n");
 		}
 		PianoDestroySearchResult (&searchResult);
-	} else {
-		BarUiMsg ("Aborted.\n");
 	}
 	if (lineBuf != NULL) {
 		free (lineBuf);