rscrobbler 0.0.6 → 0.1.0

data/lib/lastfm/track.rb

@@ -4,124 +4,243 @@ module LastFM
 
       TYPE = 'track'
 
+      # Add a list of user supplied tags to a track.
+      #
+      # @option params [String, required] :artist   the artist name
+      # @option params [String, required] :track    the track name
+      # @option params [Array,  required] :tags     array of tags to apply to this track. accepts a maximum of 10.
       # @see http://www.last.fm/api/show?service=304
-      def add_tags( track, artist, tags )
+      def add_tags( params )
         LastFM.requires_authentication
-        LastFM.post( "#{TYPE}.addTags", 'track'=>track, 'artist'=>artist, 'tags'=>tags )
+        LastFM.post( "#{TYPE}.addTags", params )
       end
 
+      # Ban a track for the current user.
+      #
+      # @option params [String, required] :artist   the artist name
+      # @option params [String, required] :track    the track name
       # @see http://www.last.fm/api/show?service=261
-      def ban( track, artist )
+      def ban( params )
         LastFM.requires_authentication
-        LastFM.post( "#{TYPE}.ban", 'track'=>track, 'artist'=>artist )
+        LastFM.post( "#{TYPE}.ban", params )
       end
 
+      # Get a list of buy Links for a track.
+      #
+      # @option params [String,  required unless :mbid] :artist         the artist name
+      # @option params [String,  required unless :mbid] :track          the track name
+      # @option params [String,  optional]              :mbid           the musicbrainz id for the track
+      # @option params [Boolean, optional]              :autocorrect    correct misspelled artist and track names to be returned in the response
+      # @option params [String,  optional]              :country        a country name, as defined by ISO 3166-1
       # @see http://www.last.fm/api/show?service=431
-      def get_buylinks( track = nil, artist = nil, mbid = nil, autocorrect = nil, country = nil )
-        raise ArgumentError unless artist && track || mbid
-        LastFM.get( "#{TYPE}.getBuylinks", !:secure, 'track'=>track, 'artist'=>artist, 'mbid'=>mbid, 'autocorrect'=>autocorrect, 'country'=>country )
+      def get_buylinks( params )
+        LastFM.get( "#{TYPE}.getBuylinks", params )
       end
 
+      # Use the last.fm corrections data to check whether the supplied track has a correction to a canonical track
+      #
+      # @option params [String, required] :artist   the artist name to correct
+      # @option params [String, required] :track    the track name to correct
       # @see http://www.last.fm/api/show?service=447
-      def get_correction( track, artist )
-        LastFM.get( "#{TYPE}.getCorrection", !:secure, 'track'=>track, 'artist'=>artist )
+      def get_correction( params )
+        LastFM.get( "#{TYPE}.getCorrection", params )
       end
 
+      # Retrieve track metadata associated with a fingerprint id generated by the Last.fm Fingerprinter.
+      # Returns track elements, along with a 'rank' value between 0 and 1 reflecting the confidence for
+      # each match.
+      #
+      # @option params [String, required] :fingerprint_id   the fingerprint id to look up
       # @see http://www.last.fm/api/show?service=441
-      def get_fingerprint_metadata( fingerprint_id )
-        LastFM.get( "#{TYPE}.getFingerPrintMetadata", !:secure, 'fingerprintid'=>fingerprint_id )
-      end
-
+      # @see https://github.com/lastfm/Fingerprinter
+      # @see http://blog.last.fm/2010/07/09/fingerprint-api-and-app-updated
+      def get_fingerprint_metadata( params )
+        LastFM.get( "#{TYPE}.getFingerPrintMetadata", params )
+      end
+
+      # Get the metadata for a track.
+      #
+      # @option params [String,  required unless :mbid] :artist         the artist name
+      # @option params [String,  required unless :mbid] :track          the track name
+      # @option params [String,  optional]              :mbid           the musicbrainz id for the track
+      # @option params [Boolean, optional]              :autocorrect    correct misspelled artist and track names to be returned in the response
+      # @option params [String,  optional]              :username       username whose playcount for, and whether they've loved, this track is to be returned in the reponse
       # @see http://www.last.fm/api/show?service=356
-      def get_info( track = nil, artist = nil, mbid = nil, autocorrect = nil, username = nil )
-        raise ArgumentError unless artist && track || mbid
-        LastFM.get( "#{TYPE}.getInfo", !:secure, 'track'=>track, 'artist'=>artist, 'mbid'=>mbid, 'autocorrect'=>autocorrect, 'username'=>username )
-      end
-
+      def get_info( params )
+        LastFM.get( "#{TYPE}.getInfo", params )
+      end
+
+      # Get shouts for a track.
+      #
+      # @option params [String,  required unless :mbid] :artist         the artist name
+      # @option params [String,  required unless :mbid] :track          the track name
+      # @option params [String,  optional]              :mbid           the musicbrainz id for the track
+      # @option params [Boolean, optional]              :autocorrect    correct misspelled artist and track names to be returned in the response
+      # @option params [Fixnum,  optional]              :page           the page number to fetch. defaults to first page
+      # @option params [Fixnum,  optional]              :limit          the number of results to fetch per page. defaults to 50
       # @see http://www.last.fm/api/show?service=453
-      def get_shouts( track = nil, artist = nil, mbid = nil, autocorrect = nil, limit = nil, page = nil )
-        raise ArgumentError unless artist && track || mbid
-        LastFM.get( "#{TYPE}.getShouts", !:secure, 'track'=>track, 'artist'=>artist, 'mbid'=>mbid, 'autocorrect'=>autocorrect, 'limit'=>limit, 'page'=>page )
+      def get_shouts( params )
+        LastFM.get( "#{TYPE}.getShouts", params )
       end
 
+      # Get similar tracks for a track on Last.fm, based on listening data.
+      #
+      # @option params [String,  required unless :mbid] :artist         the artist name
+      # @option params [String,  required unless :mbid] :track          the track name
+      # @option params [String,  optional]              :mbid           the musicbrainz id for the track
+      # @option params [Boolean, optional]              :autocorrect    correct misspelled artist and track names to be returned in the response
+      # @option params [Fixnum,  optional]              :limit          the number of results to fetch. defaults to 50
       # @see http://www.last.fm/api/show?service=319
-      def get_similar( track = nil, artist = nil, mbid = nil, autocorrect = nil, limit = nil )
-        raise ArgumentError unless artist && track || mbid
-        LastFM.get( "#{TYPE}.getSimilar", !:secure, 'track'=>track, 'artist'=>artist, 'mbid'=>mbid, 'autocorrect'=>autocorrect, 'limit'=>limit )
+      def get_similar( params )
+        LastFM.get( "#{TYPE}.getSimilar", params )
       end
 
+      # Get the tags on a track.
+      #
+      # @option params [String,  required unless :mbid] :artist         the artist name
+      # @option params [String,  required unless :mbid] :track          the track name
+      # @option params [String,  optional]              :mbid           the musicbrainz id for the track
+      # @option params [Boolean, optional]              :autocorrect    correct misspelled artist and track names to be returned in the response
+      # @option params [String,  optional]              :user           if called in non-authenticated mode you must specify the user to look up
       # @see http://www.last.fm/api/show?service=320
-      def get_tags( track = nil, artist = nil, mbid = nil, autocorrect = nil )
-        raise ArgumentError unless artist && track || mbid
-        LastFM.requires_authentication
-        LastFM.post( "#{TYPE}.getTags", 'track'=>track, 'artist'=>artist, 'mbid'=>mbid, 'autocorrect'=>autocorrect )
-      end
-
+      def get_tags( params )
+        secure = !params.include?(:user)
+        LastFM.requires_authentication if secure
+        LastFM.post( "#{TYPE}.getTags", params, secure )
+      end
+
+      # Get the top fans for a track, based on listening data.
+      #
+      # @option params [String,  required unless :mbid] :artist         the artist name
+      # @option params [String,  required unless :mbid] :track          the track name
+      # @option params [String,  optional]              :mbid           the musicbrainz id for the track
+      # @option params [Boolean, optional]              :autocorrect    correct misspelled artist and track names to be returned in the response
       # @see http://www.last.fm/api/show?service=312
-      def get_top_fans( track = nil, artist = nil, mbid = nil, autocorrect = nil )
-        raise ArgumentError unless artist && track || mbid
-        LastFM.get( "#{TYPE}.getTopFans", !:secure, 'track'=>track, 'artist'=>artist, 'mbid'=>mbid, 'autocorrect'=>autocorrect )
+      def get_top_fans( params )
+        LastFM.get( "#{TYPE}.getTopFans", params )
       end
 
+      # Get the top fans for a track, ordered by tag count.
+      #
+      # @option params [String,  required unless :mbid] :artist         the artist name
+      # @option params [String,  required unless :mbid] :track          the track name
+      # @option params [String,  optional]              :mbid           the musicbrainz id for the track
+      # @option params [Boolean, optional]              :autocorrect    correct misspelled artist and track names to be returned in the response
       # @see http://www.last.fm/api/show?service=289
-      def get_top_tags( track = nil, artist = nil, mbid = nil, autocorrect = nil )
-        raise ArgumentError unless artist && track || mbid
-        LastFM.get( "#{TYPE}.getTopTags", !:secure, 'track'=>track, 'artist'=>artist, 'mbid'=>mbid, 'autocorrect'=>autocorrect )
+      def get_top_tags( params )
+        LastFM.get( "#{TYPE}.getTopTags", params )
       end
 
+      # Love a track for the current user.
+      #
+      # @option params [String, required] :artist   the artist name
+      # @option params [String, required] :track    the track name
       # @see http://www.last.fm/api/show?service=260
-      def love( track, artist )
+      def love( params )
         LastFM.requires_authentication
-        LastFM.post( "#{TYPE}.love", 'track'=>track, 'artist'=>artist )
+        LastFM.post( "#{TYPE}.love", params )
       end
 
+      # Remove a user's tag from a track.
+      #
+      # @option params [String, required] :artist   the artist name
+      # @option params [String, required] :track    the track name
+      # @option params [String, required] :tag      a single user tag to remove from this track
       # @see http://www.last.fm/api/show?service=316
-      def remove_tag( track, artist, tag )
+      def remove_tag( params )
         LastFM.requires_authentication
-        LastFM.post( "#{TYPE}.removeTag", 'track'=>track, 'artist'=>artist, 'tag'=>tag )
-      end
-
+        LastFM.post( "#{TYPE}.removeTag", params )
+      end
+
+      # Used to add a track-play to a user's profile. Scrobble a track, or a batch of tracks.
+      # Single tracks may be passed using the Object types listed, batches of tracks must be
+      # passed in as Arrays of each Object type. Allows up to a maximum of 50 scrobbles per
+      # batch. For batch scrobbles, Array indices of optional parameters must line up with
+      # the indicies of their corresponding tracks.
+      #
+      # @option params [String,  required unless :mbid] :artist           artist name
+      # @option params [String,  required unless :mbid] :track            track name
+      # @option params [String,  optional]              :mbid             the musicbrainz id for the track
+      # @option params [Time,    optional]              :timestamp        time the track started playing
+      # @option params [String,  optional]              :album            album name
+      # @option params [String,  optional]              :album_artist     album artist, if this differend from the track artist
+      # @option params [Fixnum,  optional]              :track_number     track number of the track on the album
+      # @option params [Fixnum,  optional]              :duration         track length, in seconds
+      # @option params [String,  optional]              :stream_id        track stream id, received from the radio.getPlaylist service
+      # @option params [Boolean, optional]              :chosen_by_user   whether or not the user chose the track
+      # @option params [String,  optional]              :context          sub-client version (not public, only enabled for certain api keys)
       # @see http://www.last.fm/api/show?service=443
-      def scrobble( tracks, artists, timestamps, albums = nil, album_artists = nil, contexts = nil, stream_ids = nil, track_numbers = nil, mbids = nil, durations = nil, chosen_by_users = nil )
+      def scrobble( params )
         LastFM.requires_authentication
-        params = {}
-        %w[tracks artists timestamps albums album_artists contexts stream_ids track_numbers mbids durations chosen_by_users].each{|var|
-          camel_var = var.chomp('s').split('_').map{|a| a.capitalize}.join
-          camel_var = camel_var[0, 1].downcase + camel_var[1..-1]
-          Array(eval(var)).each_with_index{|val, i|
-            params["#{camel_var}[#{i}]"] = val
-          }
-        }
-        LastFM.post( "#{TYPE}.scrobble", params )
-      end
-
+        # Tracks are passed to the service using array notation for each of the above params
+        array_params = {}
+        params.each do |hkey, hval|
+          hval = hval.to_i if hval.is_a?(Time)
+          Array(hval).each_with_index do |aval, index|
+            array_params["#{hkey}[#{index}]"] = aval
+          end
+        end
+        LastFM.post( "#{TYPE}.scrobble", array_params )
+      end
+
+      # Search for a track by track name. Returns track matches sorted by relevance.
+      #
+      # @option params [String, required] :track    the track name
+      # @option params [String, optional] :artist   narrow results based on an artist
+      # @option params [Fixnum, optional] :page     the page number to fetch. defaults to first page
+      # @option params [Fixnum, optional] :limit    the number of results to fetch per page. defaults to 50
       # @see http://www.last.fm/api/show?service=286
-      def search( track, artist = nil, limit = nil, page = nil )
-        LastFM.get( "#{TYPE}.search", !:secure, 'track'=>track, 'artist'=>artist, 'limit'=>limit, 'page'=>page )
+      def search( params )
+        LastFM.get( "#{TYPE}.search", params )
       end
 
+      # Share a track twith one or more Last.fm users or other friends.
+      #
+      # @option params [String,  required] :artist      the artist name
+      # @option params [String,  required] :track       the track name
+      # @option params [Array,   required] :recipient   a list of email addresses or Last.fm usernames. maximum is 10
+      # @option params [String,  optional] :message     an optional message to send. if not supplied a default message will be used
+      # @option params [Boolean, optional] :public      optionally show in the sharing users activity feed. defaults to false
       # @see http://www.last.fm/api/show?service=305
-      def share( track, artist, recipient, message = nil, public = nil )
+      def share( params )
         LastFM.requires_authentication
-        LastFM.post( "#{TYPE}.share", 'track'=>track, 'artist'=>artist, 'recipient'=>recipient, 'message'=>message, 'public'=>public )
+        LastFM.post( "#{TYPE}.share", params )
       end
 
+      # Unban a track for the current user.
+      #
+      # @option params [String, required] :artist   the artist name
+      # @option params [String, required] :track    the track name
       # @see http://www.last.fm/api/show?service=449
-      def unban( track, artist )
+      def unban( params )
         LastFM.requires_authentication
-        LastFM.post( "#{TYPE}.unban", 'track'=>track, 'artist'=>artist )
+        LastFM.post( "#{TYPE}.unban", params )
       end
 
+      # Unlove a track for the current user.
+      #
+      # @option params [String, required] :artist   the artist name
+      # @option params [String, required] :track    the track name
       # @see http://www.last.fm/api/show?service=440
-      def unlove( track, artist )
+      def unlove( params )
         LastFM.requires_authentication
-        LastFM.post( "#{TYPE}.unlove", 'track'=>track, 'artist'=>artist )
-      end
-
+        LastFM.post( "#{TYPE}.unlove", params )
+      end
+
+      # Used to notify Last.fm that a user has started listening to a track.
+      #
+      # @option params [String,  required unless :mbid] :artist           artist name
+      # @option params [String,  required unless :mbid] :track            track name
+      # @option params [String,  optional]              :mbid             the musicbrainz id for the track
+      # @option params [String,  optional]              :album            album name
+      # @option params [String,  optional]              :album_artist     album artist, if this differend from the track artist
+      # @option params [Fixnum,  optional]              :track_number     track number of the track on the album
+      # @option params [Fixnum,  optional]              :duration         track length, in seconds
+      # @option params [String,  optional]              :context          sub-client version (not public, only enabled for certain api keys)
       # @see http://www.last.fm/api/show?service=454
-      def update_now_playing( track, artist, album = nil, album_artist = nil, context = nil, track_number = nil, mbid = nil, duration = nil )
+      def update_now_playing( params )
         LastFM.requires_authentication
-        LastFM.post( "#{TYPE}.updateNowPlaying", 'track'=>track, 'artist'=>artist, 'album'=>album, 'albumArtist'=>album_artist, 'context'=>context, 'trackNumber'=>track_number, 'mbid'=>mbid, 'duration'=>duration )
+        LastFM.post( "#{TYPE}.updateNowPlaying", params )
       end
 
     end

data/lib/lastfm/user.rb

@@ -4,136 +4,261 @@ module LastFM
 
       TYPE = 'user'
 
+      # Get a list of tracks by a given artist scrobbled by this user,
+      # including scrobble time. Can be limited to specific timeranges,
+      # defaults to all time.
+      #
+      # @option params [String, required] :user             last.fm username to fetch the recent tracks for
+      # @option params [String, required] :artist           the artist name to fetch tracks for
+      # @option params [Time,   optional] :startTimestamp   a unix timestamp to start at
+      # @option params [Time,   optional] :endTimestamp     a unix timestamp to end at
+      # @option params [Fixnum, optional] :page             the page number to fetch. defaults to first page
       # @see http://www.last.fm/api/show?service=432
-      def get_artist_tracks( user, artist, start_timestamp = nil, end_timestamp = nil, page = nil )
-        LastFM.get( "#{TYPE}.getArtistTracks", !:secure, 'user'=>user, 'artist'=>artist, 'startTimestamp'=>start_timestamp, 'endTimestamp'=>end_timestamp, 'page'=>page )
+      def get_artist_tracks( params )
+        LastFM.get( "#{TYPE}.getArtistTracks", params )
       end
 
+      # Get a list of tracks banned by a user.
+      #
+      # @option params [String, required] :user     last.fm username
+      # @option params [Fixnum, optional] :page     the page number to fetch. defaults to first page
+      # @option params [Fixnum, optional] :limit    the number of results to fetch per page. defaults to 50
       # @see http://www.last.fm/api/show?service=448
-      def get_banned_tracks( user, limit = nil, page = nil )
-        LastFM.get( "#{TYPE}.getBannedTracks", !:secure, 'user'=>user, 'limit'=>limit, 'page'=>page )
+      def get_banned_tracks( params )
+        LastFM.get( "#{TYPE}.getBannedTracks", params )
       end
 
+      # Get a list of upcoming events that this user is attending.
+      #
+      # @option params [String,  required] :user            last.fm username
+      # @option params [Boolean, optional] :festivalsonly   whether only festivals should be returned, or all events
+      # @option params [Fixnum,  optional] :page            the page number to fetch. defaults to first page
+      # @option params [Fixnum,  optional] :limit           the number of results to fetch per page. defaults to 50
       # @see http://www.last.fm/api/show?service=291
-      def get_events( user, limit = nil, page = nil )
-        LastFM.get( "#{TYPE}.getEvents", !:secure, 'user'=>user, 'limit'=>limit, 'page'=>page )
+      def get_events( params )
+        LastFM.get( "#{TYPE}.getEvents", params )
       end
 
+      # Get a list of the user's friends on Last.fm.
+      #
+      # @option params [String,  required] :user            last.fm username
+      # @option params [Boolean, optional] :recenttracks    whether or not to include information about friends' recent listening in the response.
+      # @option params [Fixnum,  optional] :page            the page number to fetch. defaults to first page
+      # @option params [Fixnum,  optional] :limit           the number of results to fetch per page. defaults to 50
       # @see http://www.last.fm/api/show?service=263
-      def get_friends( user, recent_tracks = nil, limit = nil, page = nil )
-        LastFM.get( "#{TYPE}.getFriends", !:secure, 'user'=>user, 'recenttracks'=>recent_tracks, 'limit'=>limit, 'page'=>page )
+      def get_friends( params )
+        LastFM.get( "#{TYPE}.getFriends", params )
       end
 
+      # Get information about a user profile.
+      #
+      # @option params [String, optional] :user   user to fetch info for. defaults to the authenticated user
       # @see http://www.last.fm/api/show?service=344
-      def get_info( user = nil )
-        LastFM.get( "#{TYPE}.getInfo", !:secure, 'user'=>user )
+      def get_info( params )
+        LastFM.get( "#{TYPE}.getInfo", params )
       end
 
+      # Get a list of tracks loved by a user.
+      #
+      # @option params [String, required] :user     last.fm username
+      # @option params [Fixnum, optional] :page     the page number to fetch. defaults to first page
+      # @option params [Fixnum, optional] :limit    the number of results to fetch per page. defaults to 50
       # @see http://www.last.fm/api/show?service=329
-      def get_loved_tracks( user, limit = nil, page = nil )
-        LastFM.get( "#{TYPE}.getLovedTracks", !:secure, 'user'=>user, 'limit'=>limit, 'page'=>page )
+      def get_loved_tracks( params )
+        LastFM.get( "#{TYPE}.getLovedTracks", params )
       end
 
+      # Get a list of a user's neighbours on Last.fm.
+      #
+      # @option params [String, required] :user     last.fm username
+      # @option params [Fixnum, optional] :limit    the number of results to fetch per page. defaults to 50
       # @see http://www.last.fm/api/show?service=264
-      def get_neighbors( user, limit = nil )
-        LastFM.get( "#{TYPE}.getNeighbonrs", !:secure, 'user'=>user, 'limit'=>limit )
+      def get_neighbors( params )
+        LastFM.get( "#{TYPE}.getNeighbonrs", params )
       end
 
+      # Gets a list of upcoming releases based on a user's musical taste.
+      #
+      # @option params [String,  required] :user      last.fm username
+      # @option params [Boolean, optional] :userecs   if true, return new releases based on artist recommendations. otherwise, it is based on their library (the default)
       # @see http://www.last.fm/api/show?service=444
-      def get_new_releases( user, useresc = nil )
-        LastFM.get( "#{TYPE}.getNewReleases", !:secure, 'user'=>user, 'useresc'=>useresc )
+      def get_new_releases( params )
+        LastFM.get( "#{TYPE}.getNewReleases", params )
       end
 
+      # Get a list of all events a user has attended in the past.
+      #
+      # @option params [String, required] :user     last.fm username
+      # @option params [Fixnum, optional] :page     the page number to fetch. defaults to first page
+      # @option params [Fixnum, optional] :limit    the number of results to fetch per page. defaults to 50
       # @see http://www.last.fm/api/show?service=343
-      def get_past_events( user, limit = nil, page = nil )
-        LastFM.get( "#{TYPE}.getPastEvents", !:secure, 'user'=>user, 'limit'=>limit, 'page'=>page )
+      def get_past_events( params )
+        LastFM.get( "#{TYPE}.getPastEvents", params )
       end
 
-      @tagging_types = [ 'artist', 'album', 'track' ]
-
+      # Get the user's personal tags.
+      #
+      # @option params [String, required] :user           last.fm username
+      # @option params [String, required] :tag            the tag you're interested in
+      # @option params [String, required] :taggingtype    the type of items which have been tagged. accepted types are 'artist', 'album', or 'track'
+      # @option params [Fixnum, optional] :page           the page number to fetch. defaults to first page
+      # @option params [Fixnum, optional] :limit          the number of results to fetch per page. defaults to 50
       # @see http://www.last.fm/api/show?service=455
-      def get_personal_tags( user, tag, tagging_type, limit = nil, page = nil )
-        raise ArgumentError unless @tagging_types.include?(tagging_type)
-        LastFM.get( "#{TYPE}.getPersonalTags", !:secure, 'user'=>user, 'tag'=>tag, 'limit'=>limit, 'page'=>page )
+      def get_personal_tags( params )
+        LastFM.get( "#{TYPE}.getPersonalTags", params )
       end
 
+      # Get a list of a user's playlists.
+      #
+      # @option params [String, required] :user   last.fm username
       # @see http://www.last.fm/api/show?service=313
-      def get_playlists( user )
-        LastFM.get( "#{TYPE}.getPlaylists", !:secure, 'user'=>user )
+      def get_playlists( params )
+        LastFM.get( "#{TYPE}.getPlaylists", params )
       end
 
+      # Get a list of the recent Stations listened to by a user.
+      #
+      # @option params [String, required] :user     last.fm username
+      # @option params [Fixnum, optional] :page     the page number to fetch. defaults to first page
+      # @option params [Fixnum, optional] :limit    the number of results to fetch per page. defaults to 50
       # @see http://www.last.fm/api/show?service=414
-      def get_recent_stations( user, limit = nil, page = nil )
+      def get_recent_stations( params )
         LastFM.requires_authentication
-        LastFM.get( "#{TYPE}.getRecentStations", :secure, 'user'=>user, 'limit'=>limit, 'page'=>page )
+        LastFM.get( "#{TYPE}.getRecentStations", params, :secure )
       end
 
+      # Get a list of the recent tracks listened to by a user. Also includes
+      # the currently playing track with the nowplaying="true" attribute if
+      # the user is currently listening.
+      #
+      # @option params [String, required] :user     last.fm username
+      # @option params [Time,   optional] :from     display scrobbles after this time, formatted as unix UTC integer timestamp
+      # @option params [Time,   optional] :to       display scrobbles before this time, formatted as unix UTC integer timestamp
+      # @option params [Fixnum, optional] :page     the page number to fetch. defaults to first page
+      # @option params [Fixnum, optional] :limit    the number of results to fetch per page. defaults to 50
       # @see http://www.last.fm/api/show?service=278
-      def get_recent_tracks( user, time_from = nil, time_to = nil, limit = nil, page = nil )
-        LastFM.get( "#{TYPE}.getRecentTracks", !:secure, 'user'=>user, 'from'=>time_from, 'to'=>time_to, 'limit'=>limit, 'page'=>page )
+      def get_recent_tracks( params )
+        LastFM.get( "#{TYPE}.getRecentTracks", params )
       end
 
+      # Get Last.fm artist recommendations for a user.
+      #
+      # @option params [Fixnum, optional] :page     the page number to fetch. defaults to first page
+      # @option params [Fixnum, optional] :limit    the number of results to fetch per page. defaults to 50
       # @see http://www.last.fm/api/show?service=388
-      def get_recommended_artists( limit = nil, page = nil )
+      def get_recommended_artists( params )
         LastFM.requires_authentication
-        LastFM.get( "#{TYPE}.getRecommendedArtists", :secure, 'limit'=>limit, 'page'=>page )
+        LastFM.get( "#{TYPE}.getRecommendedArtists", params, :secure )
       end
 
+      # Get a paginated list of all events recommended to a user by Last.fm, based on their listening profile.
+      #
+      # @option params [Fixnum, optional] :page     the page number to fetch. defaults to first page
+      # @option params [Fixnum, optional] :limit    the number of results to fetch per page. defaults to 50
       # @see http://www.last.fm/api/show?service=375
-      def get_recommended_events( limit = nil, page = nil )
+      def get_recommended_events( params )
         LastFM.requires_authentication
-        LastFM.get( "#{TYPE}.getRecommendedEvents", :secure, 'limit'=>limit, 'page'=>page )
+        LastFM.get( "#{TYPE}.getRecommendedEvents", params, :secure )
       end
 
+      # Get shouts for a user.
+      #
+      # @option params [String, required] :user     last.fm username
+      # @option params [Fixnum, optional] :page     the page number to fetch. defaults to first page
+      # @option params [Fixnum, optional] :limit    the number of results to fetch per page. defaults to 50
       # @see http://www.last.fm/api/show?service=401
-      def get_shouts( user, limit = nil, page = nil )
-        LastFM.get( "#{TYPE}.getShouts", !:secure, 'user'=>user, 'limit'=>limit, 'page'=>page )
+      def get_shouts( params )
+        LastFM.get( "#{TYPE}.getShouts", params, :secure )
       end
 
+      # Get the top albums listened to by a user, based on an optional time period.
+      #
+      # @option params [String, required] :user     last.fm username
+      # @option params [String, optional] :period   time period over which to retrieve top albums for. accepted values are 'overall', '7day', '3month', '6month' or '12month'
+      # @option params [Fixnum, optional] :page     the page number to fetch. defaults to first page
+      # @option params [Fixnum, optional] :limit    the number of results to fetch per page. defaults to 50
       # @see http://www.last.fm/api/show?service=299
-      def get_top_albums( user, period = nil, limit = nil, page = nil )
-        LastFM.get( "#{TYPE}.getTopAlbums", !:secure, 'user'=>user, 'period'=>period, 'limit'=>limit, 'page'=>page )
+      def get_top_albums( params )
+        LastFM.get( "#{TYPE}.getTopAlbums", params )
       end
 
+      # Get the top artists listened to by a user, based on an optional time period.
+      #
+      # @option params [String, required] :user     last.fm username
+      # @option params [String, optional] :period   time period over which to retrieve top artists for. accepted values are 'overall', '7day', '3month', '6month' or '12month'
+      # @option params [Fixnum, optional] :page     the page number to fetch. defaults to first page
+      # @option params [Fixnum, optional] :limit    the number of results to fetch per page. defaults to 50
       # @see http://www.last.fm/api/show?service=300
-      def get_top_artists( user, period = nil, limit = nil, page = nil )
-        LastFM.get( "#{TYPE}.getTopArtists", !:secure, 'user'=>user, 'period'=>period, 'limit'=>limit, 'page'=>page )
+      def get_top_artists( params )
+        LastFM.get( "#{TYPE}.getTopArtists", params )
       end
 
+      # Get the top tags used by a user.
+      #
+      # @option params [String, required] :user     last.fm username
+      # @option params [Fixnum, optional] :limit    the number of results to fetch per page. defaults to 50
       # @see http://www.last.fm/api/show?service=123
-      def get_top_tags( user, limit = nil )
-        LastFM.get( "#{TYPE}.getTopTags", !:secure, 'user'=>user, 'limit'=>limit )
+      def get_top_tags( params )
+        LastFM.get( "#{TYPE}.getTopTags", params )
       end
 
+      # Get the top tracks listened to by a user, based on an optional time period.
+      #
+      # @option params [String, required] :user     last.fm username
+      # @option params [String, optional] :period   time period over which to retrieve top tracks for. accepted values are 'overall', '7day', '3month', '6month' or '12month'
+      # @option params [Fixnum, optional] :page     the page number to fetch. defaults to first page
+      # @option params [Fixnum, optional] :limit    the number of results to fetch per page. defaults to 50
       # @see http://www.last.fm/api/show?service=301
-      def get_top_tracks( user, period, limit = nil, page = nil )
-        LastFM.get( "#{TYPE}.getTopTracks", !:secure, 'user'=>user, 'period'=>period, 'limit'=>limit, 'page'=>page )
+      def get_top_tracks( params )
+        LastFM.get( "#{TYPE}.getTopTracks", params )
       end
 
+      # Get an album chart for a user, for a given date range. Defaults to the most recent chart.
+      #
+      # @option params [String, required] :user     last.fm username
+      # @option params [String, optional] :from     date at which the chart should start. (see: User.get_weekly_chart_list)
+      # @option params [String, optional] :to       date at which the chart should end. (see: User.get_weekly_chart_list)
       # @see http://www.last.fm/api/show?service=279
-      def get_weekly_album_chart( user, time_from = nil, time_to = nil )
-        LastFM.get( "#{TYPE}.getWeeklyAlbumChart", !:secure, 'user'=>user, 'from'=>time_from, 'to'=>time_to )
+      def get_weekly_album_chart( params )
+        LastFM.get( "#{TYPE}.getWeeklyAlbumChart", params )
       end
 
+      # Get an artist chart for a user, for a given date range. Defaults to the most recent chart.
+      #
+      # @option params [String, required] :user     last.fm username
+      # @option params [String, optional] :from     date at which the chart should start. (see: User.get_weekly_chart_list)
+      # @option params [String, optional] :to       date at which the chart should end. (see: User.get_weekly_chart_list)
       # @see http://www.last.fm/api/show?service=281
-      def get_weekly_artist_chart( user, time_from = nil, time_to = nil )
-        LastFM.get( "#{TYPE}.getWeeklyArtistChart", !:secure, 'user'=>user, 'from'=>time_from, 'to'=>time_to )
+      def get_weekly_artist_chart( params )
+        LastFM.get( "#{TYPE}.getWeeklyArtistChart", params )
       end
 
+      # Get a list of available charts for this user, expressed as date ranges which can be sent to the chart services.
+      #
+      # @option params [String, required] :user   last.fm username
       # @see http://www.last.fm/api/show?service=280
-      def get_weekly_chart_list( user )
-        LastFM.get( "#{TYPE}.getWeeklyChartList", !:secure, 'user'=>user )
+      def get_weekly_chart_list( params )
+        LastFM.get( "#{TYPE}.getWeeklyChartList", params )
       end
 
+      # Get a track chart for a user, for a given date range. Defaults to the most recent chart.
+      #
+      # @option params [String, required] :user     last.fm username
+      # @option params [String, optional] :from     date at which the chart should start. (see: User.get_weekly_chart_list)
+      # @option params [String, optional] :to       date at which the chart should end. (see: User.get_weekly_chart_list)
       # @see http://www.last.fm/api/show?service=282
-      def get_weekly_track_chart( user, time_from = nil, time_to = nil )
-        LastFM.get( "#{TYPE}.getWeeklyTrackChart", !:secure, 'user'=>user, 'from'=>time_from, 'to'=>time_to )
+      def get_weekly_track_chart( params )
+        LastFM.get( "#{TYPE}.getWeeklyTrackChart", params )
       end
 
+      # Shout on a user's shoutbox.
+      #
+      # @option params [String, required] :user       user to shout on
+      # @option params [String, required] :message    message to post to the shoutbox
       # @see http://www.last.fm/api/show?service=411
-      def shout( user, message )
+      def shout( params )
         LastFM.requires_authentication
-        LastFM.post( "#{TYPE}.shout", 'user'=>user, 'message'=>message )
+        LastFM.post( "#{TYPE}.shout", params )
       end
 
     end