documentation for media.erl

1 files changed, 32 insertions, 37 deletions

diff --git a/server/media.erl b/server/media.erl
index 8c60f10..4710cac 100644
--- a/server/media.erl
+++ b/server/media.erl
@@ -3,23 +3,23 @@
 -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.
+%% 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
-% look at the header of the library.
+%% 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
+%% look at the header of the library.
 
-% What is an entry in our database made of? By the way the filepath includes the filename.
+%% What is an entry in our database made of? By the way the filepath includes the filename.
 
 -record(track, {title, artist, votes, locked, filepath }).
 
-% Before this module becomes usable, we must initialize it with the following steps:
-% 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 queried and files can be played.
+%% Before this module becomes usable, we must initialize it with the following steps:
+%% 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 queried and files can be played.
 
 init() ->
     mnesia:create_schema([node()]),
@@ -30,8 +30,8 @@ init() ->
     io:format("Starting to play music~n"),
     start_playing().
 
-% uses the algorithm of Brendon Hogger to split the id3-tags and
-% inserts the songs into the Database
+%% uses the Brendon Hogger's algorithm to split the id3 tags and
+%% inserts the songs into the Database
 
 read_files([FN|Rest],Total,Fail) ->
 	case id3v2:read_file(FN) of
@@ -44,14 +44,14 @@ read_files([FN|Rest],Total,Fail) ->
 	end;
 read_files([],Total,Fail) -> io:format("Total: ~w, Failed: ~w~n", [Total, Fail]).
 
-% Our loop to play music all the time, play waits on exit_status
+%% Our loop to continuously play music, play waits on exit_status
 
 start_playing() ->
 	{Artist, Title} = search_best(media:all(), 0,0),
 	play(Artist, Title).
 
 
-% Basic insertion of entries into the database. Some entries are left out because they are 0 or false.
+%% Basic insertion of entries into the database, including vote count and lock status. Some entries are left out because they are 0 or false.
 
 insert(Artist, Title, Filepath) ->
     F = fun() ->
@@ -59,10 +59,10 @@ insert(Artist, Title, Filepath) ->
         end,
     mnesia:transaction(F).
 
-% 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 most requested track is.
+%% We accomplish this by requesting all the records from the database and then iterating over them just taking a look at the vote
+%% count, so it is like list of integers. In case several tracks share the highest vote count we just take the first track with the highest vote count
+%% we found and play it. Of course the song is locked afterwards, so in case no one ever votes the playlist just cycles like a normal playlist.
 
 
 search_best([Head|Rest], Max_Votes, Track) ->
@@ -74,14 +74,14 @@ 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 (because all songs are locked) just reset all songs and start playing again...
+%% if nothing is playable anymore (because all songs are locked) just reset all songs and start from the beginning ...
 
 reset_all([Head|Rest]) ->
 	unlock(Head#track.artist, Head#track.title),
 	reset_all(Rest);
 reset_all([]) -> ok.
 
-% We want to query in order to simplify the next calls.
+%% We want to query in order to simplify the next calls.
 
 ask(Artist, Title) ->
     F = fun() ->
@@ -90,7 +90,7 @@ ask(Artist, Title) ->
     {atomic, Results} = mnesia:transaction(F),
     Results.
 
-% Just in case the client is interested in everything we have.
+%% Just in case the client is interested in everything we have.
 
 all() ->
     F = fun() ->
@@ -99,9 +99,8 @@ all() ->
     {atomic, Results} = mnesia:transaction(F),
     Results.
 
-% 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.
+%% We want to play mp3s from our database. After we have played 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.
 
 play(Artist, Title) ->
     [Head|_] = ask(Artist, Title),
@@ -117,11 +116,7 @@ play(Artist, Title) ->
 end.
 
 
-% 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.
+%% votes for a track, i.e. increases its vote count by one.
 vote(Artist, Title) ->
     F = fun() ->
                 [Head|_] = ask(Artist, Title),
@@ -131,7 +126,7 @@ vote(Artist, Title) ->
         end,
     mnesia:transaction(F).
 
-%votes against a track, i.e. decreases its vote count by one.
+%% votes against a track, i.e. decreases its vote count by one.
 devote(Artist, Title) ->
     F = fun() ->
                 [Head|_] = ask(Artist, Title),
@@ -141,7 +136,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).
+%% 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),
@@ -150,7 +145,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.
+%% locks a song so it can't be played again for a certain time.
 lock(Artist, Title) ->
     F = fun() ->
                 [Head|_] = ask(Artist, Title),
@@ -159,7 +154,7 @@ lock(Artist, Title) ->
         end,
     mnesia:transaction(F).
 
-%unlocks a song so it can be played and voted for again.
+%% unlocks a song so it can be played again.
 unlock(Artist, Title) ->
     F = fun() ->
                 [Head|_] = ask(Artist, Title),
@@ -168,8 +163,8 @@ unlock(Artist, Title) ->
         end,
     mnesia:transaction(F).
 
-% 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 a song if it was just played, after a timeout it will be unlocked automatically
+%% If all songs are locked, they will all be unlocked.
 lock_process(Artist, Title) ->
     lock(Artist, Title),
     receive