songkick_ruby 1.1.1 → 1.1.2

data/lib/songkick/client/calendar.rb

@@ -2,16 +2,46 @@ module Songkick
   class Client
     module Calendar
 
+      # Find upcoming events for an artist
+      #
+      # Example:
+      # sg = Songkick.new("myapikey")
+      # events = sg.artist_calendar(123)
+      # or events = sg.artist_calendar(123, 2)
+      #
+      # The first argument is the artist_id
+      # and the second argument is the page number,
+      # by default it is set to 1
       def artist_calendar(artist_id, page = 1)
         get "artists/#{artist_id}/calendar.#{format}", page
       end
 
+      # Find upcoming events for a location
+      #
+      # Example:
+      # sg = Songkick.new("myapikey")
+      # events = sg.location_calendar(123)
+      # or events = sg.location_calendar(123, 2)
+      #
+      # The first argument is the artist_id
+      # and the second argument is the page number,
+      # by default it is set to 1
       def location_calendar(location_id, page = 1)
         get "metro_areas/#{location_id}/calendar.#{format}", page
       end
 
+      # Find upcoming events for a user
+      #
+      # Example:
+      # sg = Songkick.new("myapikey")
+      # events = sg.users(123)
+      # or events = sg.users(123, 2)
+      #
+      # The first argument is the artist_id
+      # and the second argument is the page number,
+      # by default it is set to 1
       def user_calendar(username, page = 1)
-        get "users/#{artist_id}/calendar.#{format}", page
+        get "users/#{username}/calendar.#{format}", page
       end
 
     end

data/lib/songkick/client/event.rb

@@ -2,8 +2,14 @@ module Songkick
   class Client
     module Event
 
-      def find_event(event_id, page = 1)
-        get "events/#{event_id}.#{format}", page
+    	# Find detailed information about an event
+    	#
+    	# Example:
+    	# sg = Songkick.new("myapikey")
+    	# event = sg.find_event(123)
+    	# The first argument is the event id
+      def find_event(event_id)
+        get "events/#{event_id}.#{format}"
       end
 
     end

data/lib/songkick/client/request.rb

@@ -4,18 +4,21 @@ module Songkick
 
       private
       
-      def get(url, page)
+      # Perform a get request
+      # and returns the response body in the correct format
+      def get(url, page = 1)
         uri = generate_uri(url, page)
 
         response = Net::HTTP.get_response(uri)
         json? ? JSON.parse(response.body) : response.body
       end
 
+      # Generate uri with aditionnal options
+      # such as the page number and the api key
       def generate_uri(url, page)
         uri = API_URL + url
         uri += uri.include?("?") ? "&page=#{page}" : "?page=#{page}" if page.to_i > 1
         uri = URI.parse uri.include?("?") ? uri + "&apikey=#{api_key}" : uri + "?apikey=#{api_key}"
-        print 
         uri
       end
 

data/lib/songkick/client/search.rb

@@ -2,19 +2,55 @@ module Songkick
   class Client
     module Search
 
+      # Search for upcoming events
+      #
+      # Options:
+      # * artist_name
+      # * location
+      # * * sk
+      # * * geo
+      # * * ip
+      # * * clientip
+      # * min_date
+      # * max_date
+      #
+      # Look at this page for more information about the location option: 
+      # http://www.songkick.com/developer/event-search
+      #
+      # Example:
+      # sg = Songkick.new("myapikey")
+      # events = sg.search_events({:artist_name => "lady gaga"})
+      # events = sg.search_events({:artist_name => "lady gaga"}, 2)
+      # events = sg.search_events({:artist_name => "lady gaga", :location => "clientip=10.10.10.10"} )})
       def search_events(opts, page = 1)
         _opts = opts.collect{|k, v| "#{k}=#{v.gsub(" ", "%20")}"}.join("&")
         get "events.#{format}?#{_opts}", page
       end
       alias_method :search_event, :search_events
 
-
+      # Search for locations
+      #
+      # Options:
+      # * query
+      # * location
+      #
+      # Look at this page for more information about the location option: 
+      # http://www.songkick.com/developer/location-search
+      #
+      # Example:
+      # sg = Songkick.new("myapikey")
+      # locations = sg.search_locations({:query => "Paris"})
       def search_locations(opts, page = 1)
         _opts = opts.collect{|k, v| "#{k}=#{v.gsub(" ", "%20")}"}.join("&")
         get "search/locations.#{format}?#{_opts}", page
       end
       alias_method :search_location, :search_locations
 
+      # Search for artists
+      #
+      # Example:
+      # sg = Songkick.new("myapikey")
+      # artists = sg.search_artists("ladygaga")
       def search_artists(text, page = 1)
         get "search/artists.#{format}?query=#{text.gsub(" ","%20")}", page
       end

data/lib/songkick/client.rb

@@ -10,6 +10,8 @@ module Songkick
     
     attr_accessor :api_key, :format
 
+    # Look at the songkick.rb file for info
+    # Songkick::Client.new == Songkick.new
     def initialize(api_key, format = :json)
       @api_key = api_key
       @format = format
@@ -19,10 +21,12 @@ module Songkick
       @format = format.to_s
     end
 
+    # Clean way to know if the format is in json
     def json?
       format == 'json'
     end
-
+    
+    # Clean way to know if the format is in xml
     def xml?
       format == 'xml'
     end

data/lib/songkick.rb

@@ -7,7 +7,17 @@ require "songkick/client.rb"
 
 module Songkick
   class << self
-   
+   	
+   	# In order to use the API you must have an API key
+   	# To request one, go to this url: http://developer.songkick.com/
+   	#
+   	# Example:
+   	# sg = Songkick.new("myaipkey")
+   	# You can pass a second argument (json or xml) which is the output form.
+   	# json is the default output
+    #
+    # Songkick.new is a shortcut for songkick::Client.new
+    # You can use both, they are the same
     def new(api_key, format = :json)
       Songkick::Client.new(api_key, format)
     end

data/songkick_ruby.gemspec

@@ -1,6 +1,6 @@
 Gem::Specification.new do |s|
   s.name = "songkick_ruby"
-  s.version = "1.1.1"
+  s.version = "1.1.2"
   s.author = "Gregory Marcilhacy"
   s.email = "g.marcilhacy@gmail.com"
   s.homepage = "http://github.com/gregorym/songkick_ruby"

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification 
 name: songkick_ruby
 version: !ruby/object:Gem::Version 
-  hash: 17
+  hash: 23
   prerelease: false
   segments: 
   - 1
   - 1
-  - 1
-  version: 1.1.1
+  - 2
+  version: 1.1.2
 platform: ruby
 authors: 
 - Gregory Marcilhacy
@@ -15,7 +15,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2011-08-12 00:00:00 +02:00
+date: 2011-08-19 00:00:00 +02:00
 default_executable: 
 dependencies: 
 - !ruby/object:Gem::Dependency