Merge branch 'master' of ssh://git.animux.de/erlang

1 files changed, 21 insertions, 17 deletions

diff --git a/server/media.erl b/server/media.erl
index 165338b..5eea592 100644
--- a/server/media.erl
+++ b/server/media.erl
@@ -3,6 +3,10 @@
 -define(TESTPATTERN, "../ac/*.mp3").
 -define(TIMEOUT, 100000000).
 
+%This module is responsible for the management of the music database. 
+%It keeps track of playlist items with their current voting and locked/unlocked status 
+%and automatically selects the next song with the highest vote count to play back.
+
 % Since we are not willing to calculate and deliver all the id3 tags everytime they are requested,
 % we try to get something persistent with mnesia.
 % Concerning the parsing of id3tags we use the library id3v2 by Brendon Hogger. For detailed information take a
@@ -13,9 +17,9 @@
 -record(track, {title, artist, votes, locked, filepath }).
 
 % Before this module becomes usable, we must initialize it with the following steps:
-% 1. Initialize the mnesiadatabase and create the table within it.
+% 1. Initialize the mnesia database and create the table within it.
 % 2. Parse the mp3s in the working directory and add them to the database
-% 3. Get into a loop so the database can be actually queried and files can be played.
+% 3. Get into a loop so the database can be queried and files can be played.
 
 init() ->
     mnesia:create_schema([node()]),
@@ -40,14 +44,14 @@ read_files([FN|Rest],Total,Fail) ->
 	end;
 read_files([],Total,Fail) -> io:format("Total: ~w, Failed: ~w~n", [Total, Fail]).
 
-% Our Runloop to play music all the time, play waits on exit_status
+% Our loop to play music all the time, play waits on exit_status
 
 start_playing() ->
 	{Artist, Title} = search_best(media:all(), 0,0),
 	play(Artist, Title).
 
 
-% Basic insertion of entrys into the database. Some entries are left out because they are 0 or false.
+% Basic insertion of entries into the database. Some entries are left out because they are 0 or false.
 
 insert(Artist, Title, Filepath) ->
     F = fun() ->
@@ -70,7 +74,7 @@ search_best([Head|Rest], Max_Votes, Track) ->
 search_best([], 0, 0) -> reset_all(all());
 search_best([], _, Track) -> {Track#track.artist, Track#track.title}.
 
-% if nothing is playable anymore just reset them and start playing again...
+% if nothing is playable anymore (because all songs are locked) just reset all songs and start playing again...
 
 reset_all([Head|Rest]) ->
 	unlock(Head#track.artist, Head#track.title),
@@ -86,7 +90,7 @@ ask(Artist, Title) ->
     {atomic, Results} = mnesia:transaction(F),
     Results.
 
-% Just in case the client is interested in everything we got.
+% Just in case the client is interested in everything we have.
 
 all() ->
     F = fun() ->
@@ -95,7 +99,7 @@ all() ->
     {atomic, Results} = mnesia:transaction(F),
     Results.
 
-% We want to play mp3s from our database. After we play them they will become locked.
+% We want to play mp3s from our database. After we play them they will be locked.
 % In practice we are going to set their locked variable to true and spawn a process which will unlock them after a certain time.
 % Well this could be considered abuse.
 
@@ -111,8 +115,13 @@ play(Artist, Title) ->
 		{Port, {exit_status, 0}} -> start_playing();
 		{Port, {exit_status, S}} -> throw({commandfailed, S})
     end.
-%Increase the vote in the database so it will hopefully be played in the future
 
+
+% Of course we need a query to find out what the highest voted track is.
+% We accomplish this by requesting all the records from the database and then iterate over them, just taking a look at the vote
+% variable, so it is like a list of integers. In case no tracks were voted for we just take the first track we found and play it. Of course this song is locked afterwards so a different one will be chosen.
+
+%votes for a track, i.e. increases its vote count by one.
 vote(Artist, Title) ->
     F = fun() ->
                 [Head|_] = ask(Artist, Title),
@@ -122,8 +131,7 @@ vote(Artist, Title) ->
         end,
     mnesia:transaction(F).
 
-% decrease votes in database
-
+%votes against a track, i.e. decreases its vote count by one.
 devote(Artist, Title) ->
     F = fun() ->
                 [Head|_] = ask(Artist, Title),
@@ -133,8 +141,7 @@ devote(Artist, Title) ->
         end,
     mnesia:transaction(F).
 
-% Reset votes to zero in database
-
+%resets the vote count of selected track to 0 (this is called when the song is played).
 reset_votes(Artist, Title) ->
     F = fun() ->
                 [Head|_] = ask(Artist, Title),
@@ -143,8 +150,7 @@ reset_votes(Artist, Title) ->
         end,
     mnesia:transaction(F).
     
-% Lock a song
-
+%locks a song so it can't be played again or voted for for that time.
 lock(Artist, Title) ->
     F = fun() ->
                 [Head|_] = ask(Artist, Title),
@@ -153,8 +159,7 @@ lock(Artist, Title) ->
         end,
     mnesia:transaction(F).
 
-% Unlock a song...
-
+%unlocks a song so it can be played and voted for again.
 unlock(Artist, Title) ->
     F = fun() ->
                 [Head|_] = ask(Artist, Title),
@@ -165,7 +170,6 @@ unlock(Artist, Title) ->
 
 % Lock a song if it was just played, after a Timeout it will be unlocked automaticly
 % If all songs are locked, all will be unlocked.
-
 lock_process(Artist, Title) ->
     lock(Artist, Title),
     receive