yt 0.6.2 → 0.6.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: c4e025834f30276ff685e3ff61e3bd1330fc42b4
-  data.tar.gz: 725a5254897a04ff2ff0694125b58101dd6689aa
+  metadata.gz: 0608745d313bbcec172603a1854abfffdee3f074
+  data.tar.gz: 1f53091e0e0810f74c00a63f82584404fb640044
 SHA512:
-  metadata.gz: 582c36cde9977d2d0b7585fea15950ee1f09292ed373e39a9b99f53ae8ce32a8bdb198106d8afe00d78c60f28890eab1d9ec81f2ba5d6e9495fbc9f60c35943d
-  data.tar.gz: 3e9bb4cda3a7fec3d604c92d3c8d609b7463a20a8e833cb01ff8b8c09e40b0bf05e106d35bfc68d76a7655e6b3095e09e650244c1293555e45ae54de2175deba
+  metadata.gz: 3d79894c6d8bb6ce42e1e0ab7ee49c05f723a68eb41c2e1f32f5278979fb7e73d902af587648fb76b8cc5d18012d37220e04f84b1d463f714399a80cf46ce509
+  data.tar.gz: c393cf4018880ec464394d6c55087b8a65a99bcbf0466da48574c37927dc4232441851bf5b8f18033d361159e022dc6f584dbd68022b53849894ecd8849bcd09

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    yt (0.6.2)
+    yt (0.6.3)
       activesupport
 
 GEM
@@ -23,10 +23,10 @@ GEM
     docile (1.1.3)
     i18n (0.6.9)
     json (1.8.1)
-    mime-types (2.2)
-    minitest (5.3.3)
-    multi_json (1.10.0)
-    rake (10.3.1)
+    mime-types (2.3)
+    minitest (5.3.4)
+    multi_json (1.10.1)
+    rake (10.3.2)
     rest-client (1.6.7)
       mime-types (>= 1.16)
     rspec (3.0.0)
@@ -38,7 +38,7 @@ GEM
     rspec-expectations (3.0.0)
       diff-lcs (>= 1.2.0, < 2.0)
       rspec-support (~> 3.0.0)
-    rspec-mocks (3.0.0)
+    rspec-mocks (3.0.1)
       rspec-support (~> 3.0.0)
     rspec-support (3.0.0)
     simplecov (0.8.2)
@@ -49,9 +49,9 @@ GEM
     term-ansicolor (1.3.0)
       tins (~> 1.0)
     thor (0.19.1)
-    thread_safe (0.3.3)
-    tins (1.2.0)
-    tzinfo (1.1.0)
+    thread_safe (0.3.4)
+    tins (1.3.0)
+    tzinfo (1.2.1)
       thread_safe (~> 0.1)
     yard (0.8.7.4)
 

data/HISTORY.md

@@ -5,6 +5,7 @@ v0.6 - 2014/06/05
 * [breaking change] Account#videos shows *all* videos owned by account (public and private)
 * Add the .status association to *every* type of resource (Channel, Video, Playlist)
 * Allow account.videos to be chained with .where, such as in account.videos.where(q: 'query')
+* Retry request once when YouTube times out
 
 v0.5 - 2014/05/16
 -----------------

data/README.md

@@ -1,14 +1,16 @@
-Yt
-==
+Yt - a Ruby client for the YouTube API
+======================================================
 
-Yt helps you write apps that need to interact with the YouTube API V3.
+Yt helps you write apps that need to interact with YouTube.
 
-[![Gem Version](https://badge.fury.io/rb/yt.svg)](http://badge.fury.io/rb/yt)
-[![Dependency Status](https://gemnasium.com/Fullscreen/yt.png)](https://gemnasium.com/Fullscreen/yt)
-[![Build Status](https://travis-ci.org/Fullscreen/yt.png?branch=master)](https://travis-ci.org/Fullscreen/yt)
-[![Coverage Status](https://coveralls.io/repos/Fullscreen/yt/badge.png?)](https://coveralls.io/r/Fullscreen/yt)
-[![Code Climate](https://codeclimate.com/github/Fullscreen/yt.png)](https://codeclimate.com/github/Fullscreen/yt)
-[![Inline docs](http://inch-pages.github.io/github/Fullscreen/yt.png)](http://inch-pages.github.io/github/Fullscreen/yt)
+The **full documentation** is available at [rubydoc.info](http://rubydoc.info/github/Fullscreen/yt/master/frames).
+
+[![Build Status](http://img.shields.io/travis/Fullscreen/yt/master.svg)](https://travis-ci.org/Fullscreen/yt)
+[![Coverage Status](http://img.shields.io/coveralls/Fullscreen/yt/master.svg)](https://coveralls.io/r/Fullscreen/yt)
+[![Dependency Status](http://img.shields.io/gemnasium/Fullscreen/yt.svg)](https://gemnasium.com/Fullscreen/yt)
+[![Code Climate](http://img.shields.io/codeclimate/github/Fullscreen/yt.svg)](https://codeclimate.com/github/Fullscreen/yt)
+[![Online docs](http://img.shields.io/badge/docs-✓-green.svg)](http://rubydoc.info/github/Fullscreen/yt/master/frames)
+[![Gem Version](http://img.shields.io/gem/v/yt.svg)](http://rubygems.org/gems/yt)
 
 After [registering your app](#configuring-your-app), you can run commands like:
 
@@ -330,7 +332,7 @@ To install on your system, run
 
 To use inside a bundled Ruby project, add this line to the Gemfile:
 
-    gem 'yt', '~> 0.6.2'
+    gem 'yt', '~> 0.6.3'
 
 Since the gem follows [Semantic Versioning](http://semver.org),
 indicating the full version in your Gemfile (~> *major*.*minor*.*patch*)

data/lib/yt/collections/annotations.rb

@@ -3,14 +3,21 @@ require 'yt/models/annotation'
 
 module Yt
   module Collections
+    # Provides methods to interact with a collection of YouTube annotations.
+    # Resources with annotations are: {Yt::Models::Video videos}.
     class Annotations < Base
 
     private
 
+      # @return [Yt::Models::Annotation] a new annotation initialized with one
+      #   of the items returned by asking YouTube for a list of annotations.
       def new_item(data)
         Yt::Annotation.new data: data
       end
 
+      # @return [Hash] the parameters to submit to YouTube to list annotations.
+      # @note YouTube does not provide an API endpoint to get annotations for
+      #   a video, so we use an "old-style" URL that YouTube still maintains.
       def list_params
         super.tap do |params|
           params[:format] = :xml
@@ -21,6 +28,9 @@ module Yt
         end
       end
 
+      # @private
+      # @note Annotations overwrites +next_page+ since the list of annotations
+      #   is not paginated API-style, but in its own custom way.
       def next_page
         request = Yt::Request.new list_params
         response = request.run

data/lib/yt/collections/channels.rb

@@ -3,14 +3,21 @@ require 'yt/models/channel'
 
 module Yt
   module Collections
+    # Provides methods to interact with a collection of YouTube channels.
+    # Resources with channels are: {Yt::Models::Account accounts}.
     class Channels < Base
 
     private
 
+      # @return [Yt::Models::Channel] a new channel initialized with one of
+      #   the items returned by asking YouTube for a list of channels.
+      # @see https://developers.google.com/youtube/v3/docs/channels#resource
       def new_item(data)
         Yt::Channel.new id: data['id'], snippet: data['snippet'], auth: @auth
       end
 
+      # @return [Hash] the parameters to submit to YouTube to list channels.
+      # @see https://developers.google.com/youtube/v3/docs/channels/list
       def list_params
         super.tap do |params|
           params[:params] = {maxResults: 50, part: 'snippet', mine: true}

data/lib/yt/collections/earnings.rb

@@ -1,37 +1,13 @@
-require 'yt/collections/base'
+require 'yt/collections/reports'
 
 module Yt
   module Collections
-    class Earnings < Base
-
-      def within(days_range)
-        @days_range = days_range
-        Hash[*flat_map{|daily_earning| daily_earning}]
-      end
+    class Earnings < Reports
 
     private
 
-      def new_item(data)
-        # NOTE: could use column headers to be more precise
-        [Date.iso8601(data.first), data.last]
-      end
-
-      def list_params
-        super.tap do |params|
-          params[:path] = '/youtube/analytics/v1/reports'
-          params[:params] = {}.tap do |params|
-            params['ids'] = "contentOwner==#{@auth.owner_name}"
-            params['filters'] = "channel==#{@parent.id}"
-            params['start-date'] = @days_range.begin
-            params['end-date'] = @days_range.end
-            params['metrics'] = [:estimatedMinutesWatched, :earnings].join ','
-            params['dimensions'] = :day
-          end
-        end
-      end
-
-      def items_key
-        'rows'
+      def metrics
+        [:estimatedMinutesWatched, :earnings].join ','
       end
     end
   end

data/lib/yt/collections/partnered_channels.rb

@@ -6,6 +6,8 @@ module Yt
 
     private
 
+      # @return [Hash] the parameters to submit to YouTube to list partnered channels.
+      # @see https://developers.google.com/youtube/v3/docs/channels/list
       def list_params
         super.tap do |params|
           params[:params].delete :mine
@@ -14,6 +16,9 @@ module Yt
         end
       end
 
+      # @private
+      # @note Partnered Channels overwrites +list_resources+ since the endpoint
+      #   to hit is 'channels', not 'partnered_channels'.
       def list_resources
         self.class.superclass
       end

data/lib/yt/collections/reports.rb

@@ -0,0 +1,52 @@
+require 'yt/collections/base'
+
+module Yt
+  module Collections
+    class Reports < Base
+
+      def within(days_range)
+        @days_range = days_range
+        Hash[*flat_map{|daily_value| daily_value}]
+      end
+
+    private
+
+      def new_item(data)
+        [day_of(data), value_of(data)]
+      end
+
+      # @see https://developers.google.com/youtube/analytics/v1/content_owner_reports
+      def list_params
+        super.tap do |params|
+          params[:path] = '/youtube/analytics/v1/reports'
+          params[:params] = {}.tap do |params|
+            params['ids'] = "contentOwner==#{@auth.owner_name}"
+            params['filters'] = "channel==#{@parent.id}"
+            params['start-date'] = @days_range.begin
+            params['end-date'] = @days_range.end
+            params['metrics'] = metrics
+            params['dimensions'] = :day
+          end
+        end
+      end
+
+      def day_of(data)
+        # NOTE: could use column headers to be more precise
+        Date.iso8601 data.first
+      end
+
+      def value_of(data)
+        # NOTE: could use column headers to be more precise
+        data.last
+      end
+
+      def metrics
+        ''
+      end
+
+      def items_key
+        'rows'
+      end
+    end
+  end
+end

data/lib/yt/collections/videos.rb

@@ -3,14 +3,22 @@ require 'yt/models/video'
 
 module Yt
   module Collections
+    # Provides methods to interact with a collection of YouTube videos.
+    # Resources with videos are: {Yt::Models::Channel channels} and
+    # {Yt::Models::Account accounts}.
     class Videos < Base
 
     private
 
+      # @return [Yt::Models::Video] a new video initialized with one of
+      #   the items returned by asking YouTube for a list of videos.
+      # @see https://developers.google.com/youtube/v3/docs/videos#resource
       def new_item(data)
         Yt::Video.new id: data['id']['videoId'], snippet: data['snippet'], auth: @auth
       end
 
+      # @return [Hash] the parameters to submit to YouTube to list videos.
+      # @see https://developers.google.com/youtube/v3/docs/search/list
       def list_params
         super.tap do |params|
           params[:params] = @parent.videos_params.merge videos_params

data/lib/yt/collections/views.rb

@@ -1,37 +1,17 @@
-require 'yt/collections/base'
+require 'yt/collections/reports'
 
 module Yt
   module Collections
-    class Views < Base
-
-      def within(days_range)
-        @days_range = days_range
-        Hash[*flat_map{|daily_view| daily_view}]
-      end
+    class Views < Reports
 
     private
 
-      def new_item(data)
-        # NOTE: could use column headers to be more precise
-        [Date.iso8601(data.first), (data.last.to_i if data.last)]
-      end
-
-      def list_params
-        super.tap do |params|
-          params[:path] = '/youtube/analytics/v1/reports'
-          params[:params] = {}.tap do |params|
-            params['ids'] = "contentOwner==#{@auth.owner_name}"
-            params['filters'] = "channel==#{@parent.id}"
-            params['start-date'] = @days_range.begin
-            params['end-date'] = @days_range.end
-            params['metrics'] = :views
-            params['dimensions'] = :day
-          end
-        end
+      def metrics
+        :views
       end
 
-      def items_key
-        'rows'
+      def value_of(data)
+        data.last.to_i if data.last
       end
     end
   end

data/lib/yt/config.rb

@@ -1,53 +1,54 @@
 require 'yt/models/configuration'
 
 module Yt
-  # Provides methods to read and write runtime configuration information.
+  # Provides methods to read and write global configuration settings.
   #
-  # Configuration options are loaded from `~/.yt`, `.yt`, command line
-  # switches, and the `YT_OPTS` environment variable (listed in lowest to
-  # highest precedence).
-  #
-  # @note Config is the only module auto-loaded in the Yt module,
-  #       in order to have a syntax as easy as Yt.configure
-  #
-  # @example A server-to-server YouTube client app
+  # A typical usage is to set the API keys retrieved from the
+  # {http://console.developers.google.com Google Developers Console}.
   #
+  # @example Set the API key for a server-only YouTube app:
   #   Yt.configure do |config|
   #     config.api_key = 'ABCDEFGHIJ1234567890'
   #   end
   #
-  # @example A web YouTube client app
-  #
+  # @example Set the API client id/secret for a web-client YouTube app:
   #   Yt.configure do |config|
   #     config.client_id = 'ABCDEFGHIJ1234567890'
   #     config.client_secret = 'ABCDEFGHIJ1234567890'
   #   end
   #
+  # Note that Yt.configure has precedence over values through with
+  # environment variables (see {Yt::Models::Configuration}).
+  #
   module Config
-    # Yields the global configuration to a block.
-    # @yield [Yt::Configuration] global configuration
+    # Yields the global configuration to the given block.
     #
     # @example
     #   Yt.configure do |config|
     #     config.api_key = 'ABCDEFGHIJ1234567890'
     #   end
-    # @see Yt::Configuration
+    #
+    # @yield [Yt::Models::Configuration] The global configuration.
     def configure
       yield configuration if block_given?
     end
 
-    # Returns the global [Configuration](Yt/Configuration) object. While you
-    # _can_ use this method to access the configuration, the more common
-    # convention is to use [Yt.configure](Yt#configure-class_method).
+    # Returns the global {Yt::Models::Configuration} object.
+    #
+    # While this method _can_ be used to read and write configuration settings,
+    # it is easier to use {Yt::Config#configure} Yt.configure}.
     #
     # @example
     #     Yt.configuration.api_key = 'ABCDEFGHIJ1234567890'
-    # @see Yt.configure
-    # @see Yt::Configuration
+    #
+    # @return [Yt::Models::Configuration] The global configuration.
     def configuration
       @configuration ||= Yt::Configuration.new
     end
   end
 
+  # @note Config is the only module auto-loaded in the Yt module,
+  #       in order to have a syntax as easy as Yt.configure
+
   extend Config
 end

data/lib/yt/models/account.rb

@@ -3,14 +3,30 @@ require 'yt/associations/authentications'
 
 module Yt
   module Models
-    # Provides methods to access a YouTube account.
+    # Provides methods to interact with YouTube accounts.
+    # @see https://developers.google.com/youtube/v3/guides/authentication
     class Account < Base
       include Associations::Authentications
 
-      has_one :channel, delegate: [:videos, :playlists, :create_playlist, :delete_playlists, :update_playlists]
-      has_one :user_info, delegate: [:id, :email, :has_verified_email?, :gender, :name, :given_name, :family_name, :profile_url, :avatar_url, :locale, :hd]
+      # @!attribute channel
+      #   @return [Yt::Models::Channel] the account’s channel.
+      has_one :channel
+      delegate :playlists, :create_playlist, :delete_playlists, to: :channel
+
+      # @!attribute user_info
+      #   @return [Yt::Models::UserInfo] the account’s profile information.
+      has_one :user_info
+      delegate :id, :email, :has_verified_email?, :gender, :name,
+               :given_name, :family_name, :profile_url, :avatar_url,
+               :locale, :hd, to: :user_info
+
+      # @!attribute videos
+      #   @return [Yt::Collections::Videos] the videos owned by the account.
       has_many :videos
 
+      # @private
+      # Tells `has_many :videos` that account.videos should return all the
+      # videos *owned by* the account (public, private, unlisted).
       def videos_params
         {forMine: true}
       end

data/lib/yt/models/annotation.rb

@@ -1,82 +1,71 @@
 module Yt
   module Models
-    # Provides methods to access and analyze a single YouTube annotation.
+    # Provides methods to interact with YouTube annotations.
+    # @see https://www.youtube.com/yt/playbook/annotations.html
     class Annotation
-      # Instantiate an Annotation object from its YouTube XML representation.
-      #
-      # @note There is no documented way to access annotations through API.
-      #       There is an endpoint that returns an XML in an undocumented format,
-      #       which is here parsed into a comprehensible set of attributes.
-      #
-      # @param [String] xml_data The YouTube XML representation of an annotation
+      # @param [Hash] options the options to initialize an Annotation.
+      # @option options [String] :data The XML representation of an annotation
+      # @note YouTube API V3 does not provide access to video annotations,
+      #   therefore the XML endpoint is used to retrieve them and its response
+      #    is passed to the Annotation initializer.
       def initialize(options = {})
         @data = options[:data]
       end
 
-      # Checks whether the entire annotation box remains above y
-      #
+      # @return [Boolean] whether the text box surrounding the annotation is
+      #   completely in the top y% of the video frame.
       # @param [Integer] y Vertical position in the Youtube video (0 to 100)
-      #
-      # @return [Boolean] Whether the box remains above y
       def above?(y)
         top && top < y
       end
 
-      # Checks whether the entire annotation box remains below y
-      #
+      # @return [Boolean] whether the text box surrounding the annotation is
+      #   completely in the bottom y% of the video frame.
       # @param [Integer] y Vertical position in the Youtube video (0 to 100)
-      #
-      # @return [Boolean] Whether the box remains below y
       def below?(y)
         bottom && bottom > y
       end
 
-      # Checks whether there is a link to subscribe.
-      # Should a branding watermark also counts, because it links to the channel?
-      #
-      # @return [Boolean] Whether there is a link to subscribe in the annotation
+      # @return [Boolean] whether the annotation includes a link to subscribe.
       def has_link_to_subscribe?(options = {}) # TODO: options for which videos
         link_class == '5'
       end
 
-      # Checks whether there is a link to a video.
-      # An Invideo featured video also counts
-      #
-      # @return [Boolean] Whether there is a link to a video in the annotation
+      # @return [Boolean] whether the annotation includes a link to a video,
+      #   either directly in the text, or as an "Invideo featured video".
       def has_link_to_video?(options = {}) # TODO: options for which videos
         link_class == '1' || type == 'promotion'
       end
 
-      # Checks whether there is a link to a playlist.
-      # A link to a video with the playlist in the URL also counts
-      #
-      # @return [Boolean] Whether there is a link to a playlist in the annotation
+      # @return [Boolean] whether the annotation includes a link to a playlist,
+      #   or to a video embedded in a playlist.
       def has_link_to_playlist?
         link_class == '2' || text.include?('&list=')
       end
 
-      # Checks whether the link opens in the same window.
-      #
-      # @return [Boolean] Whether the link opens in the same window
+      # @return [Boolean] whether the annotation includes a link that will
+      #   open in the current browser window.
       def has_link_to_same_window?
         link_target == 'current'
       end
 
-      # Checks whether the annotation comes from InVideo Programming
-      #
-      # @return [Boolean] Whether the annotation comes from InVideo Programming
+      # @return [Boolean] whether the annotation is an "InVideo Programming".
       def has_invideo_programming?
         type == 'promotion' || type == 'branding'
       end
 
-      # @return [Boolean] Whether the annotation starts after the number of seconds
+      # @param [Numeric] seconds the number of seconds
+      # @return [Boolean] whether the annotation starts after the number of
+      #   seconds indicated.
       # @note This is broken for invideo programming, because they do not
       # have the timestamp in the region, but in the "data" field
       def starts_after?(seconds)
         timestamps.first > seconds if timestamps.any?
       end
 
-      # @return [Boolean] Whether the annotation starts before the number of seconds
+      # @param [Numeric] seconds the number of seconds
+      # @return [Boolean] whether the annotation starts before the number of
+      #   seconds indicated.
       # @note This is broken for invideo programming, because they do not
       # have the timestamp in the region, but in the "data" field
       def starts_before?(seconds)

data/lib/yt/models/authentication.rb

@@ -1,5 +1,7 @@
 module Yt
   module Models
+    # Provides methods to authenticate with YouTube.
+    # @see https://developers.google.com/youtube/v3/guides/authentication
     class Authentication
       attr_reader :access_token, :refresh_token, :expires_at
 

data/lib/yt/models/base.rb

@@ -5,13 +5,13 @@ require 'yt/errors/request_error'
 require 'active_support/core_ext/module/delegation' # for delegate
 require 'active_support/core_ext/string/inflections' # for camelize
 
-
 module Yt
   module Models
     class Base
       include Actions::Delete
       include Actions::Update
 
+      # @private
       def self.has_many(attributes)
         attributes = attributes.to_s
         require "yt/collections/#{attributes}"
@@ -24,9 +24,8 @@ module Yt
         end
       end
 
-      def self.has_one(attribute, options = {})
-        delegate *options[:delegate], to: attribute if options[:delegate]
-
+      # @private
+      def self.has_one(attribute)
         attributes = attribute.to_s.pluralize
         has_many attributes
 

data/lib/yt/models/channel.rb

@@ -4,30 +4,79 @@ require 'yt/associations/views'
 
 module Yt
   module Models
+    # Provides methods to interact with YouTube channels.
+    # @see https://developers.google.com/youtube/v3/docs/channels
     class Channel < Resource
       include Associations::Earnings
       include Associations::Views
 
+      # @!attribute subscriptions
+      #   @return [Yt::Collections::Subscriptions] the channel’s subscriptions.
       has_many :subscriptions
+
+      # @!attribute videos
+      #   @return [Yt::Collections::Videos] the channel’s videos.
       has_many :videos
+
+      # @!attribute playlists
+      #   @return [Yt::Collections::Playlists] the channel’s playlists.
       has_many :playlists
 
+      # Returns whether the authenticated account is subscribed to the channel.
+      #
+      # This method requires {Resource#auth auth} to return an
+      # authenticated instance of {Yt::Account}.
+      # @return [Boolean] whether the account is subscribed to the channel.
+      # @raise [Yt::Errors::Unauthorized] if {Resource#auth auth} does not
+      #   return an authenticated account.
       def subscribed?
         subscriptions.any?{|s| s.exists?}
       end
 
+      # Subscribes the authenticated account to the channel.
+      # Does not raise an error if the account was already subscribed.
+      #
+      # This method requires {Resource#auth auth} to return an
+      # authenticated instance of {Yt::Account}.
+      # @raise [Yt::Errors::Unauthorized] if {Resource#auth auth} does not
+      #   return an authenticated account.
       def subscribe
         subscriptions.insert ignore_errors: true
       end
 
+      # Subscribes the authenticated account to the channel.
+      # Raises an error if the account was already subscribed.
+      #
+      # This method requires {Resource#auth auth} to return an
+      # authenticated instance of {Yt::Account}.
+      # @raise [Yt::Errors::RequestError] if {Resource#auth auth} was already
+      #   subscribed to the channel.
+      # @raise [Yt::Errors::Unauthorized] if {Resource#auth auth} does not
+      #   return an authenticated account.
       def subscribe!
         subscriptions.insert
       end
 
+      # Unsubscribes the authenticated account from the channel.
+      # Does not raise an error if the account was not subscribed.
+      #
+      # This method requires {Resource#auth auth} to return an
+      # authenticated instance of {Yt::Account}.
+      # @raise [Yt::Errors::Unauthorized] if {Resource#auth auth} does not
+      #   return an authenticated account.
       def unsubscribe
         subscriptions.delete_all({}, ignore_errors: true)
       end
 
+      # Unsubscribes the authenticated account from the channel.
+      # Raises an error if the account was not subscribed.
+      #
+      # This method requires {Resource#auth auth} to return an
+      # authenticated instance of {Yt::Account}.
+      # @raise [Yt::Errors::RequestError] if {Resource#auth auth} was not
+      #   subscribed to the channel.
+      # @raise [Yt::Errors::Unauthorized] if {Resource#auth auth} does not
+      #   return an authenticated account.
       def unsubscribe!
         subscriptions.delete_all
       end
@@ -40,6 +89,9 @@ module Yt
         playlists.delete_all attrs
       end
 
+      # @private
+      # Tells `has_many :videos` that channel.videos should return all the
+      # videos publicly available on the channel.
       def videos_params
         {channelId: id}
       end

data/lib/yt/models/configuration.rb

@@ -1,27 +1,48 @@
 module Yt
   module Models
-    # Stores runtime configuration information.
+    # Provides an object to store global configuration settings.
     #
-    # Configuration options are loaded from `~/.yt`, `.yt`, command line
-    # switches, and the `YT_OPTS` environment variable (listed in lowest to
-    # highest precedence).
-    #
-    # @example A server-to-server YouTube client app
-    #
-    #   Yt.configure do |config|
-    #     config.api_key = 'ABCDEFGHIJ1234567890'
-    #   end
-    #
-    # @example A web YouTube client app
+    # This class is typically not used directly, but by calling
+    # {Yt::Config#configure Yt.configure}, which creates and updates a single
+    # instance of {Yt::Models::Configuration}.
     #
+    # @example Set the API client id/secret for a web-client YouTube app:
     #   Yt.configure do |config|
     #     config.client_id = 'ABCDEFGHIJ1234567890'
     #     config.client_secret = 'ABCDEFGHIJ1234567890'
     #   end
     #
+    # @see Yt::Config for more examples.
+    #
+    # An alternative way to set global configuration settings is by storing
+    # them in the following environment variables:
+    #
+    # * +YT_CLIENT_ID+ to store the Client ID for web/device apps
+    # * +YT_CLIENT_SECRET+ to store the Client Secret for web/device apps
+    # * +YT_API_KEY+ to store the API key for server/browser apps
+    #
+    # In case both methods are used together,
+    # {Yt::Config#configure Yt.configure} takes precedence.
+    #
+    # @example Set the API client id/secret for a web-client YouTube app:
+    #   ENV['YT_CLIENT_ID'] = 'ABCDEFGHIJ1234567890'
+    #   ENV['YT_CLIENT_SECRET'] = 'ABCDEFGHIJ1234567890'
+    #
     class Configuration
-      attr_accessor :api_key, :client_id, :client_secret
+      # @return [String] the Client ID for web/device YouTube applications.
+      # @see https://console.developers.google.com Google Developers Console
+      attr_accessor :client_id
+
+      # @return [String] the Client Secret for web/device YouTube applications.
+      # @see https://console.developers.google.com Google Developers Console
+      attr_accessor :client_secret
+
+      # @return [String] the API key for server/browser YouTube applications.
+      # @see https://console.developers.google.com Google Developers Console
+      attr_accessor :api_key
 
+      # Initialize the global configuration settings, using the values of
+      # the specified following environment variables by default.
       def initialize
         @client_id = ENV['YT_CLIENT_ID']
         @client_secret = ENV['YT_CLIENT_SECRET']

data/lib/yt/models/content_owner.rb

@@ -2,9 +2,16 @@ require 'yt/models/account'
 
 module Yt
   module Models
-    # Provides methods to access a YouTube content owner.
+    # Provides methods to interact with YouTube CMS accounts.
+    # @see https://cms.youtube.com
+    # @see https://developers.google.com/youtube/analytics/v1/content_owner_reports
     class ContentOwner < Account
+
+      # @!attribute partnered_channels
+      #   @return [Yt::Collection::PartneredChannels] the channels managed by the CMS account.
       has_many :partnered_channels
+
+      # @return [String] the name of the CMS account.
       attr_reader :owner_name
 
       def initialize(options = {})

data/lib/yt/models/description.rb

@@ -6,18 +6,16 @@ module Yt
     # Resources with descriptions are: videos and channels.
     #
     # @example
-    #
-    # description = Yt::Description.new 'Fullscreen provides a suite of end-to-end YouTube tools and services to many of the world’s leading brands and media companies.'
-    # description.to_s.slice(0,19) # => 'Fullscreen provides'
-    # description.length # => 127
+    #   description = Yt::Description.new 'Fullscreen provides a suite of end-to-end YouTube tools and services to many of the world’s leading brands and media companies.'
+    #   description.to_s.slice(0,19) # => 'Fullscreen provides'
+    #   description.length # => 127
     #
     class Description < String
       # Returns whether the description includes a YouTube video URL
       #
       # @example
-      #
-      # description = Yt::Description.new 'Link to video: youtube.com/watch?v=MESycYJytkU'
-      # description.has_link_to_video? #=> true
+      #   description = Yt::Description.new 'Link to video: youtube.com/watch?v=MESycYJytkU'
+      #   description.has_link_to_video? #=> true
       #
       # @return [Boolean] Whether the description includes a link to a video
       def has_link_to_video?
@@ -29,9 +27,8 @@ module Yt
       # Returns whether the description includes a YouTube channel URL
       #
       # @example
-      #
-      # description = Yt::Description.new 'Link to channel: youtube.com/fullscreen'
-      # description.has_link_to_channel? #=> true
+      #   description = Yt::Description.new 'Link to channel: youtube.com/fullscreen'
+      #   description.has_link_to_channel? #=> true
       #
       # @return [Boolean] Whether the description includes a link to a channel
       def has_link_to_channel?(options = {}) # TODO: which channel
@@ -43,9 +40,8 @@ module Yt
       # Returns whether the description includes a YouTube subscription URL
       #
       # @example
-      #
-      # description = Yt::Description.new 'Link to subscribe: youtube.com/subscription_center?add_user=fullscreen'
-      # description.has_link_to_subscribe? #=> true
+      #   description = Yt::Description.new 'Link to subscribe: youtube.com/subscription_center?add_user=fullscreen'
+      #   description.has_link_to_subscribe? #=> true
       #
       # @return [Boolean] Whether the description includes a link to subscribe
       def has_link_to_subscribe?(options = {}) # TODO: which channel
@@ -57,9 +53,8 @@ module Yt
       # Returns whether the description includes a YouTube playlist URL
       #
       # @example
-      #
-      # description = Yt::Description.new 'Link to playlist: youtube.com/playlist?list=LLxO1tY8h1AhOz0T4ENwmpow'
-      # description.has_link_to_playlist? #=> true
+      #   description = Yt::Description.new 'Link to playlist: youtube.com/playlist?list=LLxO1tY8h1AhOz0T4ENwmpow'
+      #   description.has_link_to_playlist? #=> true
       #
       # @return [Boolean] Whether the description includes a link to a playlist
       def has_link_to_playlist?

data/lib/yt/models/playlist.rb

@@ -2,7 +2,12 @@ require 'yt/models/resource'
 
 module Yt
   module Models
+    # Provides methods to interact with YouTube playlists.
+    # @see https://developers.google.com/youtube/v3/docs/playlists
     class Playlist < Resource
+
+      # @!attribute playlist_items
+      #   @return [Yt::Collections::PlaylistItems] the playlist’s items.
       has_many :playlist_items
 
       def delete

data/lib/yt/models/playlist_item.rb

@@ -2,8 +2,18 @@ require 'yt/models/base'
 
 module Yt
   module Models
+    # Provides methods to interact with YouTube playlist items.
+    # @see https://developers.google.com/youtube/v3/docs/playlistItems
     class PlaylistItem < Base
-      attr_reader :id, :video, :position
+      # @return [String] the ID that uniquely identify a YouTube playlist item.
+      attr_reader :id
+
+      # @return [String] the order in which the item appears in the playlist.
+      #   The value uses a zero-based index, so the first item has a position
+      #   of 0, the second item has a position of 1, and so forth.
+      attr_reader :position
+
+      attr_reader :video
 
       def initialize(options = {})
         @id = options[:id]

data/lib/yt/models/rating.rb

@@ -2,7 +2,12 @@ require 'yt/models/base'
 
 module Yt
   module Models
+    # Provides methods to modify the rating of a video on YouTube.
+    # @see https://developers.google.com/youtube/v3/docs/videos/rate
+    # @see https://developers.google.com/youtube/v3/docs/videos/getRating
     class Rating < Base
+      # @return [Symbol or nil] the rating of a video (if present).
+      #  Valid values are: :dislike, :like, :none, :unspecified
       attr_reader :rating
 
       def initialize(options = {})

data/lib/yt/models/request.rb

@@ -29,7 +29,7 @@ module Yt
         if response.is_a? @expected_response
           response.tap{|response| response.body = parse_format response.body}
         else
-          run_again? ? run : raise(error_for(response), request_error_message)
+          run_again? ? run : raise(response_error, request_error_message)
         end
       end
 
@@ -39,6 +39,8 @@ module Yt
         @response ||= Net::HTTP.start(*net_http_options) do |http|
           http.request http_request
         end
+      rescue OpenSSL::SSL::SSLError, Errno::ETIMEDOUT, Errno::ENETUNREACH => e
+        @response ||= e
       end
 
       def http_request
@@ -105,7 +107,7 @@ module Yt
       # random error that can be fixed by waiting for some seconds and running
       # the exact same query, or the access token needs to be refreshed.
       def run_again?
-        run_again_with_refreshed_authentication? || run_again_after_a_while?
+        refresh_token_and_retry? || server_error? && sleep_and_retry?
       end
 
       # Once in a while, YouTube responds with 500, or 503, or 400 Error and
@@ -113,17 +115,20 @@ module Yt
       # In all these cases, running the same query after some seconds fixes
       # the issue. This it not documented by YouTube and hardly testable, but
       # trying again is a workaround that works and hardly causes any damage.
-      def run_again_after_a_while?(max_retries = 1)
+      def sleep_and_retry?(max_retries = 1)
         @retries_so_far ||= -1
         @retries_so_far += 1
-        if (@retries_so_far < max_retries) && worth_another_try?
+        if (@retries_so_far < max_retries)
           @response = @http_request = @uri = nil
           sleep 3
         end
       end
 
-      def worth_another_try?
+      def server_error?
         case response
+          when OpenSSL::SSL::SSLError then true
+          when Errno::ETIMEDOUT then true
+          when Errno::ENETUNREACH then true
           when Net::HTTPServerError then true
           when Net::HTTPBadRequest then response.body =~ /did not conform/
           else false
@@ -133,26 +138,28 @@ module Yt
       # If a request authorized with an access token returns 401, then the
       # access token might have expired. If a refresh token is also present,
       # try to run the request one more time with a refreshed access token.
-      def run_again_with_refreshed_authentication?
+      def refresh_token_and_retry?
         if response.is_a? Net::HTTPUnauthorized
           @response = @http_request = @uri = nil
           @auth.refresh
         end if @auth.respond_to? :refresh
       end
 
-      def error_for(response)
-        case response
-          when Net::HTTPServerError then Errors::ServerError
+      def response_error
+        if server_error?
+          Errors::ServerError
+        else case response
           when Net::HTTPUnauthorized then Errors::Unauthorized
           when Net::HTTPForbidden then Errors::Forbidden
           else Errors::RequestError
+          end
         end
       end
 
       def request_error_message
         {}.tap do |message|
           message[:request_curl] = as_curl
-          message[:response_body] = JSON(response.body) rescue response.body
+          message[:response_body] = JSON(response.body) rescue response.inspect
         end.to_json
       end
 

data/lib/yt/models/resource.rb

@@ -6,8 +6,13 @@ module Yt
     class Resource < Base
       attr_reader :auth
       has_one :id
-      has_one :snippet, delegate: [:title, :description, :thumbnail_url, :published_at, :tags]
-      has_one :status, delegate: [:privacy_status, :public?, :private?, :unlisted?]
+
+      has_one :snippet
+      delegate :title, :description, :thumbnail_url, :published_at,
+               :tags, to: :snippet
+
+      has_one :status
+      delegate :privacy_status, :public?, :private?, :unlisted?, to: :status
 
       def initialize(options = {})
         @url = URL.new(options[:url]) if options[:url]

data/lib/yt/models/subscription.rb

@@ -2,8 +2,10 @@ require 'yt/models/base'
 
 module Yt
   module Models
+    # Provides methods to interact with YouTube subscriptions.
+    # @see https://developers.google.com/youtube/v3/docs/subscriptions
     class Subscription < Base
-
+      # @return [String] the ID that uniquely identify a YouTube subscription.
       attr_reader :id
 
       def initialize(options = {})

data/lib/yt/models/user_info.rb

@@ -2,64 +2,66 @@ require 'yt/models/base'
 
 module Yt
   module Models
+    # Provides methods to retrieve an account’s user profile.
+    # @see https://developers.google.com/+/api/latest/people/getOpenIdConnect
     class UserInfo < Base
       def initialize(options = {})
         @data = options[:data]
       end
 
-      # @return [String] User ID
+      # @return [String] the user’s ID.
       def id
         @id ||= @data.fetch 'id', ''
       end
 
-      # Return the email of the YouTube account.
-      #
-      # @return [String] Email of the YouTube account
+      # @return [String] the user’s email address.
       def email
         @email ||= @data.fetch 'email', ''
       end
 
-      # @return [Boolean] Email is verified?
+      # @return [Boolean] whether the email address is verified.
       def has_verified_email?
         @verified_email ||= @data.fetch 'verified_email', false
       end
 
-      # @return [String] name
+      # @return [String] the user's full name.
       def name
         @name ||= @data.fetch 'name', ''
       end
 
-      # @return [String] given_name
+      # @return [String] the user’s given (first) name.
       def given_name
         @given_name ||= @data.fetch 'given_name', ''
       end
 
-      # @return [String] family_name
+      # @return [String] the user’s family (last) name.
       def family_name
         @family_name ||= @data.fetch 'family_name', ''
       end
 
-      # @return [String] family_name
+      # @return [String] the URL of the user’s profile page.
       def profile_url
         @profile_url ||= @data.fetch 'link', ''
       end
 
-      # @return [String] avatar_url
+      # @return [String] the URL of the user’s profile picture.
       def avatar_url
         @avatar_url ||= @data.fetch 'picture', ''
       end
 
-      # @return [String] gender
+      # @return [String] the person’s gender. Possible values include, but
+      #   are not limited to, "male", "female", "other".
       def gender
         @gender ||= @data.fetch 'gender', ''
       end
 
-      # @return [String] locale
+      # @return [String] the user’s preferred locale.
       def locale
         @locale ||= @data.fetch 'locale', ''
       end
 
-      # @return [String] hd
+      # @return [String] the hosted domain name for the user’s Google Apps
+      #   account. For instance, example.com.
       def hd
         @hd ||= @data.fetch 'hd', ''
       end

data/lib/yt/models/video.rb

@@ -2,25 +2,64 @@ require 'yt/models/resource'
 
 module Yt
   module Models
+    # Provides methods to interact with YouTube videos.
+    # @see https://developers.google.com/youtube/v3/docs/videos
     class Video < Resource
-      has_one :details_set, delegate: [:duration]
+      # @!attribute details_set
+      #   @return [Yt::Models::DetailsSet] the video’s content details.
+      has_one :details_set
+      delegate :duration, to: :details_set
+
+      # @!attribute rating
+      #   @return [Yt::Models::Rating] the video’s rating.
       has_one :rating
+
+      # @!attribute annotations
+      #   @return [Yt::Collections::Annotations] the video’s annotations.
       has_many :annotations
 
+      # Returns whether the authenticated account likes the video.
+      #
+      # This method requires {Resource#auth auth} to return an
+      # authenticated instance of {Yt::Account}.
+      # @return [Boolean] whether the account likes the video.
+      # @raise [Yt::Errors::Unauthorized] if {Resource#auth auth} does not
+      #   return an authenticated account.
       def liked?
         rating.rating == :like
       end
 
+      # Likes the video on behalf of the authenticated account.
+      #
+      # This method requires {Resource#auth auth} to return an
+      # authenticated instance of {Yt::Account}.
+      # @return [Boolean] whether the account likes the video.
+      # @raise [Yt::Errors::Unauthorized] if {Resource#auth auth} does not
+      #   return an authenticated account.
       def like
         rating.update :like
         liked?
       end
 
+      # Dislikes the video on behalf of the authenticated account.
+      #
+      # This method requires {Resource#auth auth} to return an
+      # authenticated instance of {Yt::Account}.
+      # @return [Boolean] whether the account does not like the video.
+      # @raise [Yt::Errors::Unauthorized] if {Resource#auth auth} does not
+      #   return an authenticated account.
       def dislike
         rating.update :dislike
         !liked?
       end
 
+      # Resets the rating of the video on behalf of the authenticated account.
+      #
+      # This method requires {Resource#auth auth} to return an
+      # authenticated instance of {Yt::Account}.
+      # @return [Boolean] whether the account does not like the video.
+      # @raise [Yt::Errors::Unauthorized] if {Resource#auth auth} does not
+      #   return an authenticated account.
       def unlike
         rating.update :none
         !liked?

data/lib/yt/version.rb

@@ -1,3 +1,3 @@
 module Yt
-  VERSION = '0.6.2'
+  VERSION = '0.6.3'
 end

data/spec/models/request_spec.rb

@@ -6,11 +6,12 @@ describe Yt::Request do
   subject(:request) { Yt::Request.new host: 'example.com' }
   let(:response) { response_class.new nil, nil, nil }
   let(:response_body) { }
-  before { allow(response).to receive(:body).and_return response_body }
-  before { expect(Net::HTTP).to receive(:start).once.and_return response }
 
   describe '#run' do
     context 'given a request that returns' do
+      before { allow(response).to receive(:body).and_return response_body }
+      before { expect(Net::HTTP).to receive(:start).once.and_return response }
+
       context 'a success code 2XX' do
         let(:response_class) { Net::HTTPOK }
 
@@ -70,5 +71,73 @@ describe Yt::Request do
         it { expect{request.run}.to fail }
       end
     end
+
+    # TODO: clean up the following tests, removing repetitions
+    context 'given a request that raises' do
+      before { expect(Net::HTTP).to receive(:start).once.and_raise http_error }
+
+      # NOTE: This test is just a reflection of YouTube irrational behavior of
+      # being unavailable once in a while, and therefore causing Net::HTTP to
+      # fail, although retrying after some seconds works.
+      context 'an OpenSSL::SSL::SSLError' do
+        let(:http_error) { OpenSSL::SSL::SSLError.new }
+
+        context 'every time' do
+          before { expect(Net::HTTP).to receive(:start).at_least(:once).and_raise http_error }
+
+          it { expect{request.run}.to fail }
+        end
+
+        context 'but works the second time' do
+          before { expect(Net::HTTP).to receive(:start).at_least(:once).and_return retry_response }
+          before { allow(retry_response).to receive(:body) }
+          let(:retry_response) { Net::HTTPOK.new nil, nil, nil }
+
+          it { expect{request.run}.not_to fail }
+        end
+      end
+
+      # NOTE: This test is just a reflection of YouTube irrational behavior of
+      # being unavailable once in a while, and therefore causing Net::HTTP to
+      # fail, although retrying after some seconds works.
+      context 'an Errno::ETIMEDOUT' do
+        let(:http_error) { Errno::ETIMEDOUT.new }
+
+        context 'every time' do
+          before { expect(Net::HTTP).to receive(:start).at_least(:once).and_raise http_error }
+
+          it { expect{request.run}.to fail }
+        end
+
+        context 'but works the second time' do
+          before { expect(Net::HTTP).to receive(:start).at_least(:once).and_return retry_response }
+          before { allow(retry_response).to receive(:body) }
+          let(:retry_response) { Net::HTTPOK.new nil, nil, nil }
+
+          it { expect{request.run}.not_to fail }
+        end
+      end
+
+      # NOTE: This test is just a reflection of YouTube irrational behavior of
+      # being unavailable once in a while, and therefore causing Net::HTTP to
+      # fail, although retrying after some seconds works.
+      context 'an Errno::ENETUNREACH' do
+        let(:http_error) { Errno::ENETUNREACH.new }
+
+        context 'every time' do
+          before { expect(Net::HTTP).to receive(:start).at_least(:once).and_raise http_error }
+
+          it { expect{request.run}.to fail }
+        end
+
+        context 'but works the second time' do
+          before { expect(Net::HTTP).to receive(:start).at_least(:once).and_return retry_response }
+          before { allow(retry_response).to receive(:body) }
+          let(:retry_response) { Net::HTTPOK.new nil, nil, nil }
+
+          it { expect{request.run}.not_to fail }
+        end
+      end
+    end
   end
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: yt
 version: !ruby/object:Gem::Version
-  version: 0.6.2
+  version: 0.6.3
 platform: ruby
 authors:
 - Claudio Baccigalupo
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2014-06-11 00:00:00.000000000 Z
+date: 2014-06-12 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activesupport
@@ -136,6 +136,7 @@ files:
 - lib/yt/collections/playlist_items.rb
 - lib/yt/collections/playlists.rb
 - lib/yt/collections/ratings.rb
+- lib/yt/collections/reports.rb
 - lib/yt/collections/snippets.rb
 - lib/yt/collections/statuses.rb
 - lib/yt/collections/subscriptions.rb