documentation for media.erl

1 files changed, 21 insertions, 11 deletions

diff --git a/server/media.erl b/server/media.erl
index fbdaa7e..0ef5a44 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() ->
@@ -66,7 +70,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),
@@ -82,7 +86,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() ->
@@ -91,7 +95,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.
 
@@ -109,10 +113,11 @@ play(Artist, Title) ->
     end.
 
 
-% Of course we need a query to find out whats actually the most wished for track.
-% We will do it by requesting all the records from the database and then iteramte over just taking a look at the vote
-% variable, so it is like list of integers. In case no tracks were voted for we just take the first track we find and play it. Of course it is locked afterwards so another will be choosen.
+% 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,6 +127,7 @@ vote(Artist, Title) ->
         end,
     mnesia:transaction(F).
 
+%votes against a track, i.e. decreases its vote count by one.
 devote(Artist, Title) ->
     F = fun() ->
                 [Head|_] = ask(Artist, Title),
@@ -131,6 +137,7 @@ devote(Artist, Title) ->
         end,
     mnesia:transaction(F).
 
+%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),
@@ -139,7 +146,7 @@ reset_votes(Artist, Title) ->
         end,
     mnesia:transaction(F).
     
-
+%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),
@@ -149,6 +156,7 @@ lock(Artist, Title) ->
         end,
     mnesia:transaction(F).
 
+%unlocks a song so it can be played and voted for again.
 unlock(Artist, Title) ->
     F = fun() ->
                 [Head|_] = ask(Artist, Title),
@@ -158,6 +166,8 @@ unlock(Artist, Title) ->
         end,
     mnesia:transaction(F).
 
+%locks a song and then waits for a specified amount of time before unlocking it again.
+%this is called when the song is played.
 lock_process(Artist, Title) ->
     lock(Artist, Title),
     receive