flickrie 1.0.0 → 1.0.1

data/.gitignore

@@ -1,9 +1,9 @@
 TODO.md
 Gemfile.lock
 pkg/
-doc/
 wiki/
 .DS_Store
 api_methods.md
 .bundle/
 .rspec
+.yardoc/

data/.yardopts

@@ -0,0 +1,11 @@
+--charset    utf-8
+--readme     README.md
+--markup     markdown
+--title      "Flickrie documentation"
+--exclude    "lib/flickrie/middleware.rb"
+--exclude    "lib/flickrie/client.rb"
+--exclude    "lib/flickrie/upload_client.rb"
+--tag        api_method:"Flickr API method"
+--tag        comment
+--hide-tag   comment
+--no-private

data/CHANGELOG.md

@@ -1,44 +1,48 @@
 # Flickrie changelog
 
+## Version 1.0.1
+
+- Transfered the documentation to YARD. See the readme for the updated link.
+
 ## Version 1.0.0
 
-- Changes that are backwards compatible:
+### Changes that are backwards compatible
 
--- Fixed content type not being passed to the file you're uploading
+- Fixed content type not being passed to the file you're uploading
    if you specified it directly.
 
--- The request will now be retried once more if it timeouts
+- The request will now be retried once more if it timeouts
 
--- In authentication:
---- you can now call `request_token.authorize_url` instead of `request_token.get_authorization_url`.
---- you can now call `request_token.get_access_token(code)` instead of `Flickrie::OAuth.get_access_token(code, request_token)`.
---- you also get the infomation about the user who just authenticated,
+- In authentication:
+** you can now call `request_token.authorize_url` instead of `request_token.get_authorization_url`.
+** you can now call `request_token.get_access_token(code)` instead of `Flickrie::OAuth.get_access_token(code, request_token)`.
+** you also get the infomation about the user who just authenticated,
     which you can then access with `access_token.user_info`
     (it's a Hash with keys `:fullname`, `:user_nsid` and `:username`)
 
--- When calling `Flickrie.get_photos_counts`, the `Flickrie::MediaCount`
-   now also has attributes `#time_interval` (alias for `#date_range`),
-   `#from` and `#to`.
+- When calling `Flickrie.get_photos_counts`, the `Flickrie::MediaCount`
+  now also has attributes `#time_interval` (alias for `#date_range`),
+  `#from` and `#to`.
 
-- Changes that are **not** backwards compatible:
+### Changes that are NOT backwards compatible
 
--- If you're passing in the content type of the file you're uploading,
-   the parameter is now called `:content_type`, not `:mime_type`.
+- If you're passing in the content type of the file you're uploading,
+  the parameter is now called `:content_type`, not `:mime_type`.
 
--- If there is a problem in obtaining the access token, `Flickrie::Error`
-   is now raised, instead of `Flickrie::OAuth::Error`.
+- If there is a problem in obtaining the access token, `Flickrie::Error`
+  is now raised, instead of `Flickrie::OAuth::Error`.
 
--- When you're calling `request_token.get_authorization_url`, if you want to
-   specifiy permissions, you now have to pass the `:perms` option,
-   instead of `:permissions`. In this way you can pass any parameter,
-   and it will be appended to the URL (in case Flickr adds a new parameter).
+- When you're calling `request_token.get_authorization_url`, if you want to
+  specifiy permissions, you now have to pass the `:perms` option,
+  instead of `:permissions`. In this way you can pass any parameter,
+  and it will be appended to the URL (in case Flickr adds a new parameter).
 
--- When you have a `Flickrie::User` instance, the
-   `Flickrie::User#time_zone` now returns a struct with `#label` and
-   `#offset` attributes (before it returned a `Hash` with those keys).
+- When you have a `Flickrie::User` instance, the
+  `Flickrie::User#time_zone` now returns a struct with `#label` and
+  `#offset` attributes (before it returned a `Hash` with those keys).
 
--- When you call `Flickrie.get_media_context`, the result is now a
-   struct with attributes `#count`, `#previous`, `#next`.
+- When you call `Flickrie.get_media_context`, the result is now a
+  struct with attributes `#count`, `#previous`, `#next`.
 
 ## Version 0.7.3
 

data/README.md

@@ -45,7 +45,7 @@ You first need to install the gem.
 Then, if you're using Bundler in your project, put it into your `Gemfile`:
 
 ```ruby
-gem "flickrie"
+gem "flickrie", "~> 1.0.0"
 ```
 
 Then in your app you set the API key and shared secret (if you don't have them

data/Rakefile

@@ -8,7 +8,7 @@ task :spec do |task, args|
   system "rspec -Ispec"
 end
 
-Dir["spec/*_spec.rb"].each do |spec|
+Dir["spec/flickrie/*_spec.rb"].each do |spec|
   task_name = File.basename(spec)[/.+(?=_spec\.rb)/]
   task :"spec:#{task_name}" do
     system "rspec -Ispec #{spec}"

data/lib/flickrie.rb

@@ -1,6 +1,161 @@
+require 'flickrie/client'
+require 'flickrie/upload_client'
+require 'flickrie/middleware'
+require 'faraday_middleware'
+
+module Flickrie
+  DEFAULTS = {
+    :open_timeout => 3,
+    :timeout => 4
+  }
+
+  class << self
+    # Your API key. If you don't have one already, you can apply for it
+    # [here](http://www.flickr.com/services/apps/create/apply) (you first
+    # have to sign in).
+    attr_accessor :api_key
+
+    # Your shared secret. This goes in pair with your API key.
+    # If you don't have the API key already, you can apply for it
+    # [here](http://www.flickr.com/services/apps/create/apply) (you first
+    # have to sign in).
+    attr_accessor :shared_secret
+
+    # Time to wait for the connection to Flickr to open (in seconds).
+    # Otherwise `Faraday::Error::TimeoutError` is raised. If you're in a
+    # web application, you may want to rescue this exception and display
+    # some custom error page (telling the user to try to load the page again,
+    # for example).
+    #
+    # You may want to override this if you notice that your connection often
+    # timeouts.
+    #
+    # Defaults to 3 seconds.
+    attr_accessor :open_timeout
+
+    # Time to wait for the first block of response from Flickr to be read
+    # (in seconds). Otherwise `Faraday::Error::TimeoutError` is raised.
+    # If you're in a web application, you may want to rescue this exception
+    # and display some custom error page (telling the user to try to load
+    # the page again, for example).
+    #
+    # You may want to override this if you notice that your connection often
+    # timeouts.
+    #
+    # Defaults to 4 seconds.
+    attr_accessor :timeout
+
+    # Access token (token + secret) is used to make authenticated requests.
+    # Access tokens are unique for each Flickr user, and they last forever.
+    # So, if your app is of that kind that it asks users to authenticate through Flickr,
+    # after you get their access token, you can store it somewhere in the database,
+    # and you never have to ask that user to authenticate again.
+    #
+    # You can obtain the access token in various ways:
+    #
+    # - using this gem's [authentication proccess](https://github.com/janko-m/flickrie#authentication)
+    #
+    # - using my [flickr_auth](https://github.com/janko-m/flickr_auth) gem
+    #
+    # - using [omniauth](https://github.com/intridea/omniauth) with the
+    #   [omniauth-flickr](https://github.com/timbreitkreutz/omniauth-flickr) strategy
+    attr_accessor :access_token, :access_secret
+
+    [
+      :api_key, :shared_secret, :timeout,
+      :open_timeout, :access_token, :access_secret
+    ].
+      each do |attribute|
+        define_method "#{attribute}=" do |value|
+          instance_variable_set "@#{attribute}", value
+          @client = @upload_client = nil
+        end
+      end
+
+    # This is for manual use (for example, if I haven't covered something yet, and you really need it).
+    # Here's an example:
+    #
+    #     response = Flickrie.client.get "flickr.photos.getInfo", :photo_id => 8423943
+    #     response.body['photo']['id']          # => 8423943
+    #     response.body['photo']['description'] # => "..."
+    #
+    #     Flickrie.client.post "flickr.photos.licenses.setLicense", :photo_id => 1241497, :license_id => 2
+    #
+    # For the full list of available API methods, see [this page](http://www.flickr.com/services/api/).
+    #
+    # @return [HTTP response] A Faraday HTTP response
+    def client
+      @client ||= new_client
+    end
+
+    # @private
+    def new_client(access_token = {})
+      params = {
+        :url => 'http://api.flickr.com/services/rest',
+        :params => {
+          :format => 'json',
+          :nojsoncallback => '1',
+          :api_key => api_key
+        },
+        :request => {
+          :open_timeout => open_timeout || DEFAULTS[:open_timeout],
+          :timeout => timeout || DEFAULTS[:timeout]
+        }
+      }
+
+      Client.new(params) do |b|
+        b.use Middleware::Retry
+        b.use FaradayMiddleware::OAuth,
+          :consumer_key => api_key,
+          :consumer_secret => shared_secret,
+          :token => access_token[:token] || self.access_token,
+          :token_secret => access_token[:secret] || self.access_secret
+
+        b.use Middleware::StatusCheck
+        b.use FaradayMiddleware::ParseJson
+        b.use Middleware::OAuthCheck
+
+        b.adapter :net_http
+      end
+    end
+
+    # @private
+    def upload_client
+      @upload_client ||= new_upload_client
+    end
+
+    # @private
+    def new_upload_client(access_token = {})
+      params = {
+        :url => 'http://api.flickr.com/services',
+        :request => {
+          :open_timeout => open_timeout || DEFAULTS[:open_timeout]
+        }
+      }
+
+      UploadClient.new(params) do |b|
+        b.use Middleware::Retry
+        b.use FaradayMiddleware::OAuth,
+          :consumer_key => api_key,
+          :consumer_secret => shared_secret,
+          :token => access_token[:token] || self.access_token,
+          :token_secret => access_token[:secret] || self.access_secret
+        b.request :multipart
+
+        b.use Middleware::UploadStatusCheck
+        b.use FaradayMiddleware::ParseXml
+        b.use Middleware::OAuthCheck
+
+        b.adapter :net_http
+      end
+    end
+  end
+end
+
 require 'flickrie/api_methods'
-require 'flickrie/instance'
 
 module Flickrie
   extend ApiMethods
 end
+
+require 'flickrie/instance'

data/lib/flickrie/api_methods.rb

@@ -13,14 +13,20 @@ require 'flickrie/ticket'
 
 module Flickrie
   module ApiMethods
-    # ==== Example
+    # For uploading photos and videos to Flickr. Example:
     #
-    #   path = File.expand_path("photo.jpg")
-    #   id = Flickrie.upload(path, :title => "Me and Jessica", :description => "...")
-    #   photo = Flickrie.get_photo_info(id)
-    #   photo.title # => "Me and Jessica"
+    #     path = File.expand_path("photo.jpg")
+    #     photo_id = Flickrie.upload(path, :title => "Me and Jessica", :description => "...")
+    #     photo = Flickrie.get_photo_info(photo_id)
+    #     photo.title # => "Me and Jessica"
     #
-    # If the <tt>:async => 1</tt> option is passed, returns the ticket ID.
+    # If the `:async => 1` option is passed, returns the ticket ID (see {#check\_upload\_tickets}).
+    #
+    # @param media [File, String] A file or a path to the file you want to upload
+    # @param params [Hash] Options for uploading (see [this page](http://www.flickr.com/services/api/upload.api.html))
+    # @return [String] New photo's ID, or ticket's ID, if `:async => 1` is passed
+    #
+    # @note This method requires authentication with "write" permissions.
     def upload(media, params = {})
       response = upload_client.upload(media, params)
       if params[:async] == 1
@@ -30,15 +36,20 @@ module Flickrie
       end
     end
 
-    # ==== Example
+    # For replacing photos and videos on Flickr. Example:
+    #
+    #     path = File.expand_path("photo.jpg")
+    #     photo_id = 42374 # ID of the photo to be replaced
+    #     id = Flickrie.replace(path, photo_id)
     #
-    #   path = File.expand_path("photo.jpg")
-    #   photo_id = 42374 # ID of the photo to be replaced
-    #   id = Flickrie.replace(path, photo_id, :title => "Me and Jessica", :description => "...")
-    #   photo = Flickrie.get_photo_info(id)
-    #   photo.title # => "Me and Jessica"
+    # If the `:async => 1` option is passed, returns the ticket ID (see {#check\_upload\_tickets}).
     #
-    # If the <tt>:async => 1</tt> option is passed, returns the ticket ID.
+    # @param media [File, String] A file or a path to the file you want to upload
+    # @param media_id [String, Fixnum] The ID of the photo/video to be replaced
+    # @param params [Hash] Options for replacing (see [this page](http://www.flickr.com/services/api/replace.api.html))
+    # @return [String] New photo's ID, or ticket's ID, if `:async => 1` is passed
+    #
+    # @note This method requires authentication with "write" permissions.
     def replace(media, media_id, params = {})
       response = upload_client.replace(media, media_id, params)
       if params[:async] == 1
@@ -48,94 +59,199 @@ module Flickrie
       end
     end
 
-    #--
-    # people
+    # Fetches the Flickr user with the given email.
+    #
+    # @param email [String]
+    # @return [Flickrie::User]
+    # @api_method [flickr.people.findByEmail](http://www.flickr.com/services/api/flickr.people.findByEmail.html)
     def find_user_by_email(email, params = {})
       response = client.find_user_by_email(email, params)
       User.from_find(response.body['user'])
     end
 
+    # Fetches the Flickr user with the given username.
+    #
+    # @param username [String]
+    # @return [Flickrie::User]
+    # @api_method [flickr.people.findByUsername](http://www.flickr.com/services/api/flickr.people.findByUsername.html)
     def find_user_by_username(username, params = {})
       response = client.find_user_by_username(username, params)
       User.from_find(response.body['user'])
     end
 
-    def get_user_info(user_nsid, params = {})
-      response = client.get_user_info(user_nsid, params)
+    # Fetches the Flickr user with the given NSID.
+    #
+    # @param nsid [String]
+    # @return [Flickrie::User]
+    # @api_method [flickr.people.getInfo](http://www.flickr.com/services/api/flickr.people.getInfo.html)
+    def get_user_info(nsid, params = {})
+      response = client.get_user_info(nsid, params)
       User.from_info(response.body['person'])
     end
 
-    def media_from_user(user_nsid, params = {})
-      response = client.media_from_user(user_nsid, params)
+    # Fetches photos and videos from the Flickr user with the given NSID.
+    #
+    # @param nsid [String]
+    # @return [Array<Flickrie::Photo, Flickrie::Video>]
+    # @api_method [flickr.people.getPhotos](http://www.flickr.com/services/api/flickr.people.getPhotos.html)
+    #
+    # @note This method requires authentication with "read" permissions.
+    def media_from_user(nsid, params = {})
+      response = client.media_from_user(nsid, params)
       Media.from_user(response.body['photos'])
     end
-    def photos_from_user(user_nsid, params = {})
-      media_from_user(user_nsid, params).
+    # Fetches photos from the Flickr user with the given NSID.
+    #
+    # @param nsid [String]
+    # @return [Array<Flickrie::Photo>]
+    # @api_method [flickr.people.getPhotos](http://www.flickr.com/services/api/flickr.people.getPhotos.html)
+    #
+    # @note This method requires authentication with "read" permissions.
+    def photos_from_user(nsid, params = {})
+      media_from_user(nsid, params).
         select { |media| media.is_a?(Photo) }
     end
-    def videos_from_user(user_nsid, params = {})
-      media_from_user(user_nsid, params).
+    # Fetches videos from the Flickr user with the given NSID.
+    #
+    # @param nsid [String]
+    # @return [Array<Flickrie::Video>]
+    # @api_method [flickr.people.getPhotos](http://www.flickr.com/services/api/flickr.people.getPhotos.html)
+    #
+    # @note This method requires authentication with "read" permissions.
+    def videos_from_user(nsid, params = {})
+      media_from_user(nsid, params).
         select { |media| media.is_a?(Video) }
     end
 
-    def public_media_from_user(user_nsid, params = {})
-      response = client.public_media_from_user(user_nsid, params)
+    # Fetches public photos and videos from the Flickr user with the given
+    # NSID.
+    #
+    # @param nsid [String]
+    # @return [Array<Flickrie::Photo, Flickrie::Video>]
+    # @api_method [flickr.people.getPublicPhotos](http://www.flickr.com/services/api/flickr.people.getPublicPhotos.html)
+    def public_media_from_user(nsid, params = {})
+      response = client.public_media_from_user(nsid, params)
       Media.from_user(response.body['photos'])
     end
-    def public_photos_from_user(user_nsid, params = {})
-      public_media_from_user(user_nsid, params).
+    # Fetches public photos from the Flickr user with the given NSID.
+    #
+    # @param nsid [String]
+    # @return [Array<Flickrie::Photo>]
+    # @api_method [flickr.people.getPublicPhotos](http://www.flickr.com/services/api/flickr.people.getPublicPhotos.html)
+    def public_photos_from_user(nsid, params = {})
+      public_media_from_user(nsid, params).
         select { |media| media.is_a?(Photo) }
     end
-    def public_videos_from_user(user_nsid, params = {})
-      public_media_from_user(user_nsid, params).
+    # Fetches public videos from the Flickr user with the given NSID.
+    #
+    # @param nsid [String]
+    # @return [Array<Flickrie::Video>]
+    # @api_method [flickr.people.getPublicPhotos](http://www.flickr.com/services/api/flickr.people.getPublicPhotos.html)
+    def public_videos_from_user(nsid, params = {})
+      public_media_from_user(nsid, params).
         select { |media| media.is_a?(Video) }
     end
 
-    #--
-    # photos
+    # Add tags to the photo/video with the given ID.
+    #
+    # @param media_id [String, Fixnum]
+    # @param tags [String] A space delimited string with tags
+    # @api_method [flickr.photos.addTags](http://www.flickr.com/services/api/flickr.photos.addTags.html)
+    #
+    # @note This method requires authentication with "write" permissions.
     def add_media_tags(media_id, tags, params = {})
       client.add_media_tags(media_id, tags, params)
+      nil
     end
     alias add_photo_tags add_media_tags
     alias add_video_tags add_media_tags
 
+    # Deletes the photo/video with the given ID.
+    #
+    # @param media_id [String, Fixnum]
+    # @api_method [flickr.photos.delete](http://www.flickr.com/services/api/flickr.photos.delete.html)
+    #
+    # @note This method requires authentication with "delete" permissions.
     def delete_media(media_id, params = {})
       client.delete_media(media_id, params)
-      media_id
+      nil
     end
     alias delete_photo delete_media
     alias delete_video delete_media
 
+    # Fetches photos and videos from contacts of the user who authenticated.
+    #
+    # @param params [Hash] Options for this API method (see the link below)
+    # @return [Array<Flickrie::Photo, Flickrie::Video>]
+    # @api_method [flickr.photos.getContactsPhotos](http://www.flickr.com/services/api/flickr.photos.getContactsPhotos.html)
+    #
+    # @note This method requires authentication with "read" permissions.
     def media_from_contacts(params = {})
       response = client.media_from_contacts(params)
       Media.from_contacts(response.body['photos'])
     end
+    # Fetches photos from contacts of the user who authenticated.
+    #
+    # @param params [Hash] Options for this API method (see the link below)
+    # @return [Array<Flickrie::Photo>]
+    # @api_method [flickr.photos.getContactsPhotos](http://www.flickr.com/services/api/flickr.photos.getContactsPhotos.html)
+    #
+    # @note This method requires authentication with "read" permissions.
     def photos_from_contacts(params = {})
       media_from_contacts(params).select { |media| media.is_a?(Photo) }
     end
+    # Fetches videos from contacts of the user who authenticated.
+    #
+    # @param params [Hash] Options for this API method (see the link below)
+    # @return [Array<Flickrie::Video>]
+    # @api_method [flickr.photos.getContactsPhotos](http://www.flickr.com/services/api/flickr.photos.getContactsPhotos.html)
+    #
+    # @note This method requires authentication with "read" permissions.
     def videos_from_contacts(params = {})
       media_from_contacts(params).select { |media| media.is_a?(Video) }
     end
 
-    def public_media_from_user_contacts(user_nsid, params = {})
-      response = client.public_media_from_user_contacts(user_nsid, params)
+    # Fetches public photos and videos from contacts of the user with the
+    # given NSID.
+    #
+    # @param nsid [String]
+    # @param params [Hash] Options for this API method (see the link below)
+    # @api_method [flickr.photos.getContactsPublicPhotos](http://www.flickr.com/services/api/flickr.photos.getContactsPublicPhotos.html)
+    def public_media_from_user_contacts(nsid, params = {})
+      response = client.public_media_from_user_contacts(nsid, params)
       Media.from_contacts(response.body['photos'])
     end
-    def public_photos_from_user_contacts(user_nsid, params = {})
-      public_media_from_user_contacts(user_nsid, params).
+    # Fetches public photos from contacts of the user with the
+    # given NSID.
+    #
+    # @param nsid [String]
+    # @param params [Hash] Options for this API method (see the link below)
+    # @api_method [flickr.photos.getContactsPublicPhotos](http://www.flickr.com/services/api/flickr.photos.getContactsPublicPhotos.html)
+    def public_photos_from_user_contacts(nsid, params = {})
+      public_media_from_user_contacts(nsid, params).
         select { |media| media.is_a?(Photo) }
     end
-    def public_videos_from_user_contacts(user_nsid, params = {})
-      public_media_from_user_contacts(user_nsid, params).
+    # Fetches public videos from contacts of the user with the
+    # given NSID.
+    #
+    # @param nsid [String]
+    # @param params [Hash] Options for this API method (see the link below)
+    # @api_method [flickr.photos.getContactsPublicPhotos](http://www.flickr.com/services/api/flickr.photos.getContactsPublicPhotos.html)
+    def public_videos_from_user_contacts(nsid, params = {})
+      public_media_from_user_contacts(nsid, params).
         select { |media| media.is_a?(Photo) }
     end
 
-    # ==== Example
+    # Fetches context of the photo/video with the given ID. Example:
+    #
+    #     context = Flickrie.get_photo_context(37124234)
+    #     context.count    # => 23
+    #     context.previous # => #<Photo: id=2433240, ...>
+    #     context.next     # => #<Video: id=1282404, ...>
     #
-    #   context = Flickrie.get_photo_context(37124234)
-    #   context.count    # => 23
-    #   context.previous # => #<Photo: id=2433240, ...>
-    #   context.next     # => #<Video: id=1282404, ...>
+    # @param media_id [String, Fixnum]
+    # @return [Struct]
+    # @api_method [flickr.photos.getContext](http://www.flickr.com/services/api/flickr.photos.getContext.html)
     def get_media_context(media_id, params = {})
       response = client.get_media_context(media_id, params)
       Media.from_context(response.body)
@@ -143,7 +259,21 @@ module Flickrie
     alias get_photo_context get_media_context
     alias get_video_context get_media_context
 
-    # Returns instances of Flickrie::MediaCount
+    # Fetches numbers of photos and videos for given date ranges. Example:
+    #
+    #     require 'date'
+    #     dates = [DateTime.parse("3rd Jan 2011").to_time, DateTime.parse("11th Aug 2011").to_time]
+    #     counts = Flickrie.get_media_counts(:taken_dates => dates.map(&:to_i).join(','))
+    #
+    #     count = counts.first
+    #     count.value            # => 24
+    #     count.date_range       # => 2011-01-03 01:00:00 +0100..2011-08-11 02:00:00 +0200
+    #     count.date_range.begin # => 2011-01-03 01:00:00 +0100
+    #     count.from             # => 2011-01-03 01:00:00 +0100
+    #
+    # @param params [Hash] Options for this API method (see the link below)
+    # @return [Flickrie::MediaCount]
+    # @api_method [flickr.photos.getCounts](http://www.flickr.com/services/api/flickr.photos.getCounts.html)
     def get_media_counts(params = {})
       response = client.get_media_counts \
         MediaCount.ensure_utc(params)
@@ -153,28 +283,71 @@ module Flickrie
     alias get_photos_counts get_media_counts
     alias get_videos_counts get_media_counts
 
-    # See Flickrie::Media#exif for details
+    # Fetches the exif for the photo with the given ID. Example:
+    #
+    #     photo = Flickrie.get_photo_exif(27234987)
+    #     photo.exif.get('Model') # => 'Canon PowerShot G12'
+    #
+    #     photo.exif.get('X-Resolution', :data => 'raw')   # => '180'
+    #     photo.exif.get('X-Resolution', :data => 'clean') # => '180 dpi'
+    #     photo.exif.get('X-Resolution')                   # => '180 dpi'
+    #
+    # @param photo_id [String, Fixnum]
+    # @return [Flickrie::Photo]
+    # @api_method [flickr.photos.getExif](http://www.flickr.com/services/api/flickr.photos.getExif.html)
     def get_photo_exif(photo_id, params = {})
       response = client.get_media_exif(photo_id, params)
       Photo.from_exif(response.body['photo'])
     end
-    # See Flickrie::Media#exif for details
+    # Fetches the exif for the video with the given ID. Example:
+    #
+    #     video = Flickrie.get_video_exif(27234987)
+    #     video.exif.get('Model') # => 'Canon PowerShot G12'
+    #
+    #     video.exif.get('X-Resolution', :data => 'raw')   # => '180'
+    #     video.exif.get('X-Resolution', :data => 'clean') # => '180 dpi'
+    #     video.exif.get('X-Resolution')                   # => '180 dpi'
+    #
+    # @param video_id [String, Fixnum]
+    # @return [Flickrie::Video]
+    # @api_method [flickr.photos.getExif](http://www.flickr.com/services/api/flickr.photos.getExif.html)
     def get_video_exif(video_id, params = {})
       response = client.get_media_exif(video_id, params)
       Video.from_exif(response.body['photo'])
     end
 
-    # Returns instances of Flickrie::User
+    # Fetches the list of users who favorited the photo with the given ID.
+    # Example:
+    #
+    #     photo = Flickrie.get_photo_favorites(24810948)
+    #     photo.favorites.first.username # => "John Smith"
+    #
+    # @param photo_id [String, Fixnum]
+    # @return [Flickrie::Photo]
+    # @api_method [flickr.photos.getFavorites](http://www.flickr.com/services/api/flickr.photos.getFavorites.html)
     def get_photo_favorites(photo_id, params = {})
       response = client.get_media_favorites(photo_id, params)
       Photo.new(response.body['photo'])
     end
-    # Returns instances of Flickrie::User
+    # Fetches the list of users who favorited the video with the given ID.
+    # Example:
+    #
+    #     video = Flickrie.get_video_favorites(24810948)
+    #     video.favorites.first.username # => "John Smith"
+    #
+    # @param video_id [String, Fixnum]
+    # @return [Flickrie::Video]
+    # @api_method [flickr.photos.getFavorites](http://www.flickr.com/services/api/flickr.photos.getFavorites.html)
     def get_video_favorites(video_id, params = {})
       response = client.get_media_favorites(video_id, params)
       Video.new(response.body['photo'])
     end
 
+    # Fetches info of the photo/video with the given ID.
+    #
+    # @param media_id [String, Fixnum]
+    # @return [Flickrie::Photo, Flickrie::Video]
+    # @api_method [flickr.photos.getInfo](http://www.flickr.com/services/api/flickr.photos.getInfo.html)
     def get_media_info(media_id, params = {})
       response = client.get_media_info(media_id, params)
       Media.from_info(response.body['photo'])
@@ -182,81 +355,158 @@ module Flickrie
     alias get_photo_info get_media_info
     alias get_video_info get_media_info
 
-    # Returns an instance of Flickrie::Photo
+    # Fetches the sizes of the photo with the given ID. Example:
+    #
+    #     photo = Flickrie.get_photo_sizes(242348)
+    #     photo.medium!(500)
+    #     photo.size       # => "Medium 500"
+    #     photo.source_url # => "http://farm8.staticflickr.com/7090/7093101501_9337f28800.jpg"
+    #
+    # @param photo_id [String, Fixnum]
+    # @return [Flickrie::Photo]
+    # @api_method [flickr.photos.getSizes](http://www.flickr.com/services/api/flickr.photos.getSizes.html)
     def get_photo_sizes(photo_id, params = {})
       response = client.get_media_sizes(photo_id, params)
       Photo.from_sizes(response.body['sizes'])
     end
-    # Returns an instance of Flickrie::Video
+    # Fetches the sizes of the video with the given ID. Example:
+    #
+    #     video = Flickrie.get_video_sizes(438492)
+    #     video.download_url # => "..."
+    #
+    # @param video_id [String, Fixnum]
+    # @return [Flickrie::Video]
+    # @api_method [flickr.photos.getSizes](http://www.flickr.com/services/api/flickr.photos.getSizes.html)
     def get_video_sizes(video_id, params = {})
       response = client.get_media_sizes(video_id, params)
       Video.from_sizes(response.body['sizes'])
     end
 
+    # Remove the tag with the given ID
+    #
+    # @param tag_id [String]
+    # @api_method [flickr.photos.removeTag](http://www.flickr.com/services/api/flickr.photos.removeTag.html)
+    #
+    # @note This method requires authentication with "write" permissions.
     def remove_media_tag(tag_id, params = {})
       client.remove_media_tag(tag_id, params)
+      nil
     end
     alias remove_photo_tag remove_media_tag
     alias remove_video_tag remove_media_tag
 
+    # Fetches photos and videos matching a certain criteria.
+    #
+    # @param search_params [Hash] Options for searching (see the link below)
+    # @return [Array<Flickrie::Photo, Flickrie::Video>]
+    # @api_method [flickr.photos.search](http://www.flickr.com/services/api/flickr.photos.search.html)
     def search_media(search_params = {})
       response = client.search_media(search_params)
       Media.from_search(response.body['photos'])
     end
+    # Fetches photos matching a certain criteria.
+    #
+    # @param search_params [Hash] Options for searching (see the link below)
+    # @return [Array<Flickrie::Photo>]
+    # @api_method [flickr.photos.search](http://www.flickr.com/services/api/flickr.photos.search.html)
     def search_photos(search_params = {})
       search_media(search_params.merge(:media => 'photos'))
     end
+    # Fetches videos matching a certain criteria.
+    #
+    # @param search_params [Hash] Options for searching (see the link below)
+    # @return [Array<Flickrie::Video>]
+    # @api_method [flickr.photos.search](http://www.flickr.com/services/api/flickr.photos.search.html)
     def search_videos(search_params = {})
       search_media(search_params.merge(:media => 'videos'))
     end
 
-    #--
-    # photos.upload
-    #++
-    # Returns an array of Flickrie::Ticket
-    def check_upload_tickets(tickets, params = {})
-      tickets = tickets.join(',') if tickets.respond_to?(:join)
-      response = client.check_upload_tickets(tickets, params)
-      response.body['uploader']['ticket'].
-        map { |info| Ticket.new(info) }
-    end
-
-    #--
-    # licenses
-    #++
-    # Returns an array of Flickrie::License
+    # Fetches all available types of licenses.
+    #
+    # @return [Array<Flickrie::License>]
+    # @api_method [flickr.photos.licenses.getInfo](http://www.flickr.com/services/api/flickr.photos.licenses.getInfo.html)
     def get_licenses(params = {})
       response = client.get_licenses(params)
       License.from_hash(response.body['licenses']['license'])
     end
 
-    #--
-    # photosets
+    # Fetches upload tickets with given IDs. Example:
+    #
+    #     photo = File.open("...")
+    #     ticket_id = Flickrie.upload(photo)
+    #     sleep(10)
+    #
+    #     ticket = Flickrie.check_upload_tickects(ticket_id)
+    #     if ticket.complete?
+    #       puts "Photo was uploaded, and its ID is #{ticket.photo_id}"
+    #     end
+    #
+    # @param tickets [String] A space delimited string with ticket IDs
+    # @return [Flickrie::Ticket]
+    # @api_method [flickr.photos.upload.checkTickets](http://www.flickr.com/services/api/flickr.photos.upload.checkTickets.html)
+    def check_upload_tickets(tickets, params = {})
+      ticket_ids = tickets.join(',') rescue tickets
+      response = client.check_upload_tickets(ticket_ids, params)
+      response.body['uploader']['ticket'].
+        map { |info| Ticket.new(info) }
+    end
+
+    # Fetches information about the set with the given ID.
+    #
+    # @param set_id [String, Fixnum]
+    # @return [Flickrie::Set]
+    # @api_method [flickr.photosets.getInfo](http://www.flickr.com/services/api/flickr.photosets.getInfo.html)
     def get_set_info(set_id, params = {})
       response = client.get_set_info(set_id, params)
       Set.from_info(response.body['photoset'])
     end
 
-    def sets_from_user(user_nsid, params = {})
-      response = client.sets_from_user(user_nsid, params)
-      Set.from_user(response.body['photosets']['photoset'], user_nsid)
+    # Fetches sets from a user with the given NSID.
+    #
+    # @param nsid [String]
+    # @return [Array<Flickrie::Set>]
+    # @api_method [flickr.photosets.getList](http://www.flickr.com/services/api/flickr.photosets.getList.html)
+    def sets_from_user(nsid, params = {})
+      response = client.sets_from_user(nsid, params)
+      Set.from_user(response.body['photosets']['photoset'], nsid)
     end
 
+    # Fetches photos and videos from a set with the given ID.
+    #
+    # @param set_id [String]
+    # @param params [Hash] Options for this API method (see the link below)
+    # @return [Array<Flickrie::Photo, Flickrie::Video>]
+    # @api_method [flickr.photosets.getPhotos](http://www.flickr.com/services/api/flickr.photosets.getPhotos.html)
     def media_from_set(set_id, params = {})
       response = client.media_from_set(set_id, params)
       Media.from_set(response.body['photoset'])
     end
+    # Fetches photos from a set with the given ID.
+    #
+    # @param set_id [String]
+    # @param params [Hash] Options for this API method (see the link below)
+    # @return [Array<Flickrie::Photo>]
+    # @api_method [flickr.photosets.getPhotos](http://www.flickr.com/services/api/flickr.photosets.getPhotos.html)
     def photos_from_set(set_id, params = {})
       media_from_set(set_id, params.merge(:media => 'photos'))
     end
+    # Fetches videos from a set with the given ID.
+    #
+    # @param set_id [String]
+    # @param params [Hash] Options for this API method (see the link below)
+    # @return [Array<Flickrie::Video>]
+    # @api_method [flickr.photosets.getPhotos](http://www.flickr.com/services/api/flickr.photosets.getPhotos.html)
     def videos_from_set(set_id, params = {})
       media_from_set(set_id, params.merge(:media => 'videos'))
     end
 
-    #--
-    # test
-    #++
-    # Returns an instance of Flickrie::User
+    # Tests if the authentication was successful. If it was, it
+    # returns info of the user who just authenticated.
+    #
+    # @return [Flickrie::User]
+    # @api_method [flickr.test.login](http://www.flickr.com/services/api/flickr.test.login.html)
+    #
+    # @note This method requires authentication with "read" permissions.
     def test_login(params = {})
       response = client.test_login(params)
       User.from_test(response.body['user'])