Finish first wave of documentation.

[rbdr/lyricli.rb] / lib / lyricli / source_manager.rb

diff --git a/lib/lyricli/source_manager.rb b/lib/lyricli/source_manager.rb
index 3befbd2ab0b6037bd29b457c318d7e51a40b25a6..3514c3408579db0ef7cb41404ed4685c6ee17bcf 100644 (file)
--- a/lib/lyricli/source_manager.rb
+++ b/lib/lyricli/source_manager.rb
@@ -1,8 +1,12 @@
 module Lyricli
+
+  # Manages the different sources. SourceManager is in charge of enabling and
+  # disabling them, as well as getting the current track.
   class SourceManager
 
     include Util
 
+    # Creates a new instance of SourceManager
     def initialize
       @enabled_sources = []
       @config = Configuration.instance
@@ -16,6 +20,11 @@ module Lyricli
       end
     end
 
+    # Enables a source. This runs the source's enable method and adds it to the
+    # `enabled_sources` configuration key. It will only enable sources that
+    # are "available" (see #available_sources)
+    #
+    # @param [String] source_name the name of the source to enable
     def enable(source_name)
       if available_sources.include?(source_name)
         if klass = parse_class(camelize(source_name))
@@ -31,6 +40,10 @@ module Lyricli
       end
     end
 
+    # Disables a source. This only removes the source from the `enabled_sources`
+    # configuration key.
+    #
+    # @param [String] source_name the name of the source to disable
     def disable(source_name)
       if available_sources.include?(source_name)
         if klass = parse_class(camelize(source_name))
@@ -44,6 +57,10 @@ module Lyricli
       end
     end
 
+    # Resets a source. This runs the source's reset method. It will also disable
+    # them.
+    #
+    # @param [String] source_name the name of the source to reset.
     def reset(source_name)
       if available_sources.include?(source_name)
         if klass = parse_class(camelize(source_name))
@@ -57,6 +74,9 @@ module Lyricli
       end
     end
 
+    # Iterates over every source to attempt to retrieve the current song.
+    #
+    # @return [Hash] the current track, has an `:artist` and `:song` key.
     def current_track
       track = nil
       lock = false
@@ -78,24 +98,34 @@ module Lyricli
       track
     end
 
+    # Returns an array with the available sources. Optionally formats the result
+    # so active sources are identified by an appended *
+    #
+    # @param [Boolean] format whether or not to render the stars for active
+    #                         sources.
+    # @return [Array] the names of the currently available sources.
     def available_sources(format = false)
       path_root = File.expand_path(File.dirname(__FILE__))
       sources = Dir[path_root+"/sources/*.rb"].map{ |s|
         name = s.split("/").last.gsub(/\.rb/, "")
-
-        # Add a star to denote enabled sources
         name
       }
 
       # Remove arguments (Hack?) We don't want anybody to touch tihs one.
       sources.delete("arguments")
       if format
+        # Add a star to denote enabled sources
         format_sources(sources)
       else
         sources
       end
     end
 
+    # Adds a star to all members of the array that correspond to an active
+    # source
+    #
+    # @param [Array] sources the array of sources to format
+    # @return [Array] the formatted array
     def format_sources(sources)
       sources.map{ |s|
         s << "*" if @config["enabled_sources"].include?(s)