yt 0.7.2 → 0.7.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 6dc19edffeaae2714ad047a40032115520edd738
-  data.tar.gz: 3f71e513ce00e106d65739806406953b4388f0b6
+  metadata.gz: 280089714e1281d849dcb959a4de6e8bed69b76f
+  data.tar.gz: 8d2482b21d1ba9827c9a8172aab4475c36348c51
 SHA512:
-  metadata.gz: 08d1aa16ee0d6ddbe7f6b15098cbd72bfcbe9e9901bbcf87d1b6abf15e0d10fc73af313173d149fd6610bb73b4e40ace2536579ccbca618030dc97e76da332d9
-  data.tar.gz: ae6645e795bdb55896d4844e9824ce0e3001a8f4a39210418887bbeaa221cef15ecc4ca4ab2f6e6ac0d21a3fcae4409e9f7a080e3171dc5ecabace67b63c0ea9
+  metadata.gz: 14db211427304d5eb03b6d62f50190eb50f614e8e0c9c68d6d7ff26c19ae88378f8feb4502cfaafb2e0ee15e0be0c7aa1d7aa01ff3fc211481b59b4257261a2b
+  data.tar.gz: 811037e6baf6cfc47c73cb3efd4a64ed5cb1b7c0f1aa0dfffa06ec4ee73106dbb7f26fe92b1b040b3ff5a72026c2076f5d05a3b5d2b4b7143fb22d8e652385a8

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    yt (0.7.2)
+    yt (0.7.3)
       activesupport
 
 GEM

data/HISTORY.md

@@ -9,6 +9,7 @@ v0.7 - 2014/06/18
 * More snippet methods for PlaylistItem (channel_id, channel_title, playlist_id, video_id)
 * More status methods for PlaylistItem (privacy_status, public?, private?, unlisted?)
 * Add video.update to update title, description, tags and categoryId of a video
+* Sort channel.videos by most recent first
 
 v0.6 - 2014/06/05
 -----------------

data/README.md

@@ -19,23 +19,14 @@ channel = Yt::Channel.new id: 'UCxO1tY8h1AhOz0T4ENwmpow'
 channel.title #=> "Fullscreen"
 channel.public? #=> true
 channel.comment_count #=> 773
-channel.videos.count #=> 13
+channel.videos.count #=> 12
 ```
 
 ```ruby
 video = Yt::Video.new id: 'MESycYJytkU'
 video.title #=> "Fullscreen Creator Platform"
-video.public? #=> true
-video.view_count #=> 55843
 video.comment_count #=> 308
-video.like_count #=> 556
-video.dislike_count #=> 78
-video.favorite_count #=> 0
-video.duration #=> 86
 video.hd? #=> true
-video.stereoscopic? #=> false
-video.captioned? #=> true
-video.licensed? #=> false
 video.annotations.count #=> 1
 ```
 
@@ -51,14 +42,18 @@ Use [Yt::Account](http://rubydoc.info/github/Fullscreen/yt/master/Yt/Models/Acco
 
 * authenticate as a YouTube account
 * read the attributes of the account
-* access the YouTube channel of the account
+* access the channel managed by the account
+* access the videos uploaded by the account
 
 ```ruby
-# An account can be initialized with access token, refresh token or an authorization code
+# Accounts can be initialized with access token, refresh token or an authorization code
 account = Yt::Account.new access_token: 'ya29.1.ABCDEFGHIJ'
 
 account.email #=> .. your e-mail address..
 account.channel #=> #<Yt::Models::Channel @id=...>
+
+account.videos.count #=> 12
+account.videos.first #=> #<Yt::Models::Video @id=...>
 ```
 
 *All the above methods require authentication (see below).*
@@ -72,7 +67,7 @@ Use [Yt::ContentOwner](http://rubydoc.info/github/Fullscreen/yt/master/Yt/Models
 * list the channels partnered with a YouTube content owner
 
 ```ruby
-# A content owner is an account, therefore can be initialized with access token, refresh token or an authorization code
+# Content owners can be initialized with access token, refresh token or an authorization code
 content_owner = Yt::ContentOwner.new owner_name: 'CMSname', access_token: 'ya29.1.ABCDEFGHIJ'
 
 content_owner.partnered_channels.count #=> 12
@@ -99,13 +94,13 @@ channel = Yt::Channel.new id: 'UCxO1tY8h1AhOz0T4ENwmpow'
 channel.title #=> "Fullscreen"
 channel.description #=> "The first media company for the connected generation."
 channel.description.has_link_to_playlist? #=> false
-channel.thumbnail_url #=> "https://yt3.ggpht.com/-KMnbKDBl60w/AAAAAAAAAAI/AAAAAAAAAAA/NjmFYOCVig4/s88-c-k-no/photo.jpg"
+channel.thumbnail_url #=> "https://yt3.ggpht.com/-KMnbKDBl60w/.../photo.jpg"
 channel.published_at #=> 2006-03-23 06:13:25 UTC
 channel.public? #=> true
 
 channel.view_count #=> 421619
 channel.comment_count #=> 773
-channel.video_count #=> 13
+channel.video_count #=> 12
 channel.subscriber_count #=> 136925
 channel.subscriber_count_visible? #=> true
 
@@ -127,7 +122,6 @@ channel.subscribe #=> true
 
 channel.create_playlist title: 'New playlist' #=> true
 channel.delete_playlists title: 'New playlist' #=> [true]
-
 ```
 
 *The methods above require to be authenticated as a YouTube account (see below).*
@@ -137,10 +131,10 @@ content_owner = Yt::ContentOwner.new owner_name: 'CMSname', access_token: 'ya29.
 channel = Yt::Channel.new id: 'UCxO1tY8h1AhOz0T4ENwmpow', auth: content_owner
 
 channel.earnings_on 5.days.ago #=> 12.23
-channel.earnings since: 3.days.ago, until: 2.days.ago #=> {Wed, 28 May 2014 => 1.34, Thu, 29 May 2014 => 0.47}
+channel.earnings until: 2.days.ago #=> {Wed, 28 May 2014 => 1.34, Thu, 29 May 2014 => 0.47}
 
 channel.views_on 5.days.ago #=> 44
-channel.views since: 3.days.ago, until: 2.days.ago #=> {Wed, 28 May 2014 => 12, Thu, 29 May 2014 => 3}
+channel.views since: 3.days.ago #=> {Wed, 28 May 2014 => 12, Thu, 29 May 2014 => 3}
 ```
 
 *The methods above require to be authenticated as the channel’s content owner (see below).*
@@ -159,7 +153,7 @@ Use [Yt::Video](http://rubydoc.info/github/Fullscreen/yt/master/Yt/Models/Video)
 video = Yt::Video.new id: 'MESycYJytkU'
 
 video.title #=> "Fullscreen Creator Platform"
-video.description #=> "The new Fullscreen Creator Platform gives creators and brands a suite of exclusive Fullscreen Apps to build, manage and monetize their YouTube audience..."
+video.description #=> "The new Fullscreen Creator Platform gives creators and brands a suite..."
 video.description.has_link_to_channel? #=> true
 video.thumbnail_url #=> "https://i1.ytimg.com/vi/MESycYJytkU/default.jpg"
 video.published_at #=> 2013-07-09 16:27:32 UTC
@@ -193,7 +187,7 @@ video.like #=> true
 *The methods above require to be authenticated as a YouTube account (see below).*
 
 ```ruby
-video.update title: 'New title', description: 'New description', tags: ['new tag'], categoryId: '21'
+video.update title: 'A title', description: 'A description', tags: ['a tag'], categoryId: '21'
 ```
 
 *The methods above require to be authenticated as the video’s owner (see below).*
@@ -213,7 +207,7 @@ Use [Yt::Playlist](http://rubydoc.info/github/Fullscreen/yt/master/Yt/Models/Pla
 playlist = Yt::Playlist.new id: 'PLSWYkYzOrPMRCK6j0UgryI8E0NHhoVdRc'
 
 playlist.title #=> "Fullscreen Features"
-playlist.description #=> "You send us your best videos and we feature our favorite ones throughout the week!"
+playlist.description #=> "You send us your best videos and we feature our favorite ones..."
 playlist.description.has_link_to_subscribe? #=> false
 playlist.thumbnail_url #=> "https://i1.ytimg.com/vi/36kL2alg7Jk/default.jpg"
 playlist.published_at #=> 2012-11-27 21:23:38 UTC
@@ -224,14 +218,12 @@ playlist.channel_title #=> "Fullscreen"
 
 playlist.playlist_items.count #=> 1
 playlist.playlist_items.first #=> #<Yt::Models::PlaylistItem @id=...>
-playlist.playlist_items.first.position #=> 0
-playlist.playlist_items.first.video.title #=> "Fullscreen Creator Platform"
 ```
 
 *The methods above do not require authentication.*
 
 ```ruby
-playlist.update title: 'New title', description: 'New description', tags: ['new tag'], privacy_status: 'private'
+playlist.update title: 'title', description: 'desc', tags: ['new tag'], privacy_status: 'private'
 playlist.add_video 'MESycYJytkU'
 playlist.add_videos ['MESycYJytkU', 'MESycYJytkU']
 playlist.delete_playlist_items title: 'Fullscreen Creator Platform' #=> [true]
@@ -262,7 +254,6 @@ item.playlist_id #=> "PLSWYkYzOrPMRCK6j0UgryI8E0NHhoVdRc"
 item.position #=> 0
 item.video_id #=> "W4GhTprSsOY"
 item.video #=> #<Yt::Models::Video @id=...>
-
 ```
 
 *The methods above do not require authentication.*
@@ -296,23 +287,34 @@ Configuring your app
 ====================
 
 In order to use Yt you must register your app in the [Google Developers Console](https://console.developers.google.com).
-Depending on the nature of your app, you should pick one of the following strategies.
+
+If you don’t have a registered app, browse to the console and select "Create Project":
+![01-create-project](https://cloud.githubusercontent.com/assets/7408595/3373043/4224c894-fbb0-11e3-9f8a-4d96bddce136.png)
+
+When your project is ready, select APIs & Auth in the menu and enable Google+, YouTube Analytics and YouTube Data API:
+![02-select-api](https://cloud.githubusercontent.com/assets/7408595/3373046/4226ea34-fbb0-11e3-9a44-872871e8b297.png)
+
+The next step is to create an API key. Depending on the nature of your app, you should pick one of the following strategies.
 
 Apps that do not require user interactions
 ------------------------------------------
 
 If you are building a read-only app that fetches public data from YouTube, then
-generate a **Public API access** key in the Google Console.
-Next, add the following snippet of code to the initializer of your app:
+all you need is a **Public API access**.
+
+Click on "Create new Key" in the Public API section and select "Server Key":
+![03-create-key](https://cloud.githubusercontent.com/assets/7408595/3373045/42258fcc-fbb0-11e3-821c-699c8a3ce7bc.png)
+![04-create-server-key](https://cloud.githubusercontent.com/assets/7408595/3373044/42251db2-fbb0-11e3-93f9-8f06f8390b4e.png)
+
+Once the key for server application is created, copy the API key and add it
+to your code with the following snippet of code (replacing with your own key):
 
 ```ruby
 Yt.configure do |config|
-  config.api_key = '123456789012345678901234567890'
+  config.api_key = 'AIzaSyAO8dXpvZcaP2XSDFBD91H8yQ'
 end
 ```
 
-replacing the value above with your own key for server application.
-
 Remember: this kind of app is not allowed to perform any destructive operation,
 so you won’t be able to like a video, subscribe to a channel or delete a
 playlist from a specific account. You will only be able to retrieve read-only
@@ -330,14 +332,15 @@ Just pass that access token to the account initializer, such as:
 ```ruby
 account = Yt::Account.new access_token: 'ya29.1.ABCDEFGHIJ'
 account.email #=> (retrieves the account’s e-mail address)
-account.playlists.first.add_video 'MESycYJytkU' #=> (adds a video to an account’s playlist)
+account.videos #=> (lists a video to an account’s playlist)
 ```
 
 Scenario 2. If you don’t have the account’s access token, but you have the
 **refresh token**, then it’s almost as easy.
-Open the [Google Developers Console](https://console.developers.google.com),
-find the client ID and client secret of the **web application** that you used to obtain the
-refresh token, then add the following snippet of code to the initializer of your app:
+In the [Google Developers Console](https://console.developers.google.com),
+find the web application that was used to obtain the refresh token, copy the
+Client ID and Client secret and add them to you code with the following snippet
+of code (replacing with your own keys):
 
 ```ruby
 Yt.configure do |config|
@@ -345,38 +348,53 @@ Yt.configure do |config|
   config.client_secret = '1234567890'
 end
 ```
-
-replacing the values above with the client ID and secret for web application.
 Then you can manage a YouTube account by passing the refresh token to the
 account initializer, such as:
 
 ```ruby
 account = Yt::Account.new refresh_token: '1/1234567890'
 account.email #=> (retrieves the account’s e-mail address)
-account.playlists.first.add_video 'MESycYJytkU' #=> (adds a video to an account’s playlist)
+account.videos #=> (lists a video to an account’s playlist)
 ```
 
 Scenario 3. If you don’t have any account’s token, then you can get one by
-having the user authorize your app through the Google OAuth page. First,
-build the the Google OAuth page URL with the following code:
+having the user authorize your app through the Google OAuth page.
+
+In the [Google Developers Console](https://console.developers.google.com),
+click on "Create new Client ID" in the OAuth section and select "Web application":
+![06-create-client-key](https://cloud.githubusercontent.com/assets/7408595/3373047/42379eba-fbb0-11e3-89c4-16b10e072de6.png)
+
+Fill the "Authorized Redirect URI" textarea with the URL of your app where you
+want to redirect users after they authorize their YouTube account.
+
+Once the Client ID for web application is created, copy the Client ID and secret
+and add them to your code with the following snippet of code (replacing with your own keys):
+
+```ruby
+Yt.configure do |config|
+  config.client_id = '49781862760-4t610gtk35462g.apps.googleusercontent.com'
+  config.client_secret = 'NtFHjZkJcwYZDfYVz9mp8skz9'
+end
+```
+
+Finally, in your web app, add a link to the URL generated by running
 
 ```ruby
 Yt::Account.new(scopes: scopes, redirect_uri: redirect_uri).authentication_url
 ```
 
-where `scopes` is the list of scopes you want the user to authorize, and
-`redirect_uri` is the page of your web app the user should come back after
-authorizing (remember, this must be added to the Google Console as well).
-Sample scopes are: `youtube`, `youtube.readonly` `userinfo.email`.
+where `redirect_uri` is the URL you entered in the form above, and `scopes` is
+the list of YouTube scopes you want the user to authorize. Depending on the
+nature of your app, you can pick one or more among `youtube`, `youtube.readonly` `userinfo.email`.
 
-After authorizing your app, the user will be redirected to `redirect_uri`
+Every user who authorizes your app will be redirected to the `redirect_uri`
 with an extra `code` parameter that looks something like `4/Ja60jJ7_Kw0`.
 Just pass the code to the following method to authenticate and initialize the account:
 
 ```ruby
 account = Yt::Account.new authorization_code: '4/Ja60jJ7_Kw0'
 account.email #=> (retrieves the account’s e-mail address)
-account.playlists.first.add_video 'MESycYJytkU' #=> (adds a video to an account’s playlist)
+account.videos #=> (lists a video to an account’s playlist)
 ```
 
 Configuring with environment variables
@@ -386,7 +404,6 @@ As an alternative to the approach above, you can configure your app with
 variables. Setting the following environment variables:
 
 ```bash
-export YT_CLIENT_SCENARIO="device_app"
 export YT_CLIENT_ID="1234567890.apps.googleusercontent.com"
 export YT_CLIENT_SECRET="1234567890"
 export YT_API_KEY="123456789012345678901234567890"
@@ -405,7 +422,6 @@ end
 so use the approach that you prefer.
 If a variable is set in both places, then `Yt.configure` takes precedence.
 
-
 How to install
 ==============
 
@@ -415,7 +431,7 @@ To install on your system, run
 
 To use inside a bundled Ruby project, add this line to the Gemfile:
 
-    gem 'yt', '~> 0.7.2'
+    gem 'yt', '~> 0.7.3'
 
 Since the gem follows [Semantic Versioning](http://semver.org),
 indicating the full version in your Gemfile (~> *major*.*minor*.*patch*)
@@ -442,15 +458,9 @@ How to test
 
 Yt comes with two different sets of tests:
 
-1. tests in `spec/models` and `spec/collections` **do not hit** the YouTube API
+1. tests in `spec/models`, `spec/collections` and `spec/errors` **do not hit** the YouTube API
 1. tests in `spec/associations` **hit** the YouTube API and require authentication
 
-To run all the tests, type:
-
-```bash
-rspec
-```
-
 The reason why some tests actually hit the YouTube API is because they are
 meant to really integrate Yt with YouTube. YouTube API is not exactly
 *the most reliable* API out there, so we need to make sure that the responses
@@ -460,70 +470,46 @@ You don’t have to run all the tests every time you change code.
 Travis CI is already set up to do this for when whenever you push a branch
 or create a pull request for this project.
 
-Testing models and collections
-------------------------------
-
-To only run tests against models and collections (which do not hit the API), type:
+To only run tests against models, collections and errors (which do not hit the API), type:
 
 ```bash
-rspec spec/models spec/collections
+rspec spec/models spec/collections spec/errors
 ```
 
-Testing associations
---------------------
-
-To only run tests against associations (which hit the API), type:
+To also run live-tests against the YouTube API, type:
 
 ```bash
-rspec spec/associations
+rspec
 ```
 
-This test will fail at first. As documented by the error message, you will need
-an app registered in the [Google Developers Console](https://console.developers.google.com)
-to proceed.
-
-Browse to the Console, then create a new app that you will only use for testing.
+This will fail unless you have set up a test YouTube application and some
+tests YouTube accounts to hit the API. Once again, you probably don’t need
+this, since Travis CI already takes care of running this kind of tests.
 
-Under the "APIs" tab of this app, enable 'Google+ API', 'Youtube Analytics
-API' and 'YouTube Data API v3'.
-
-Under the "Credentials" tab of this app, create a new 'Key for server
-application' and a new 'Client ID' and 'Client Secret' for **native** application.
-
-It’s important that you pick 'native application' instead of 'web application',
-otherwise running your tests will require you to open a browser and launch a
-local webserver… and you don’t need to do any of that.
-
-Finally, copy the given values and set the following environment variables:
-
-```bash
-export YT_TEST_DEVICE_CLIENT_ID="1234567890.apps.googleusercontent.com"
-export YT_TEST_DEVICE_CLIENT_SECRET="1234567890"
-export YT_TEST_SERVER_API_KEY="123456789012345678901234567890"
-```
-
-[ TODO:
-  Complete this section.
-  Explain how get and store the refresh token, making sure all the required scopes are authorized:
-  'https://www.googleapis.com/auth/youtube https://www.googleapis.com/auth/userinfo.email https://www.googleapis.com/auth/userinfo.profile'
-]
+How to contribute
+=================
 
+Yt needs your support!
+The goal of Yt is to provide a Ruby interface for all the methods exposed by
+the [YouTube Data API (v3)](https://developers.google.com/youtube/v3) and by
+the [YouTube Analytics API](https://developers.google.com/youtube/analytics).
 
+If you find that a method is missing, fork the project, add the missing code,
+write the appropriate tests, then submit a pull request, and it will gladly
+be merged!
 
-How to contribute
-=================
+How to release new versions
+===========================
 
-Before you submit a pull request, make sure all the tests are passing and the
-code is fully test-covered.
+If you are a manager of this project, remember to upgrade the [Yt gem](http://rubygems.org/gems/yt)
+whenever a new feature is added or a bug gets fixed.
 
-To release an updated version of the gem to Rubygems, run:
+Make sure all the tests are passing on [Travis CI](https://travis-ci.org/Fullscreen/yt),
+document the changes in HISTORY.md and README.md, bump the version, then run
 
     rake release
 
-Remember to *bump the version* before running the command, and to document
-your changes in HISTORY.md and README.md if required.
-
-The yt gem follows [Semantic Versioning](http://semver.org).
+Remember that the yt gem follows [Semantic Versioning](http://semver.org).
 Any new release that is fully backward-compatible should bump the *patch* version (0.0.x).
 Any new version that breaks compatibility should bump the *minor* version (0.x.0)
 

data/lib/yt/associations/authentications.rb

@@ -7,7 +7,8 @@ module Yt
   module Associations
     # Provides authentication methods to YouTube resources, which
     # allows to access to content detail set-specific methods like `access_token`.
-    # YouTube resources with authentication are: accounts.
+    #
+    # YouTube resources with authentication are: {Yt::Models::Account accounts}.
     module Authentications
       delegate :access_token, :refresh_token, :expires_at, to: :authentication
 

data/lib/yt/associations/earnings.rb

@@ -2,32 +2,24 @@ require 'yt/collections/earnings'
 
 module Yt
   module Associations
-    # Provides the `has_many :earnings` method to YouTube resources, which
-    # allows to invoke earning-related methods, such as .earnings.
-    # YouTube resources with earning are: channels.
+    # Provides methods which allows to access the earnings generated by a resource.
+    #
+    # YouTube resources with earning are: {Yt::Models::Channel channels}.
     module Earnings
-      # Return the estimated earnings for one specific day.
-      #
+      # @return [Float] the estimated earnings for one specific day in USD.
       # @param [Date or Time or DateTime or String] date The date to obtain
-      # the estimated earnings for. If String, must be Date-parseable.
-      #
-      # @return [Float] The estimated earnings in USD.
+      #   the estimated earnings for. If +String+, must be Date-parseable.
       def earnings_on(date)
         earnings(from: date, to: date).values.first
       end
 
-      # Return the estimated earnings for a range of days.
-      #
+      # @return [Hash] the estimated earnings for a range of days. Each +key+ is a +Date+
+      #   and each +value+ is a +Float+, representing estimated earnings in USD.
       # @param [Hash] options the range of days to get the earnings for.
       # @option options [Date or Time or DateTime or String] :since The start
-      # of the days range. If String, must be Date-parseable.
-      # @note options[:since] is aliased as options[:from]
+      #   of the days range. If +String+, must be Date-parseable. Also aliased as *:from*.
       # @option options [Date or Time or DateTime or String] :until The end
-      # of the days range. If String, must be Date-parseable.
-      # @note options[:until] is aliased as options[:to]
-      #
-      # @return [Hash] The estimated earnings by day. Each :key is a Date
-      # and each :value is a Float, representing estimated earnings in USD.
+      #   of the days range. If +String+, must be Date-parseable. Also aliased as *:to*.
       def earnings(options = {})
         from = options[:since] || options[:from] || 6.days.ago
         to = options[:until] || options[:to] || 2.days.ago

data/lib/yt/associations/views.rb

@@ -2,32 +2,24 @@ require 'yt/collections/views'
 
 module Yt
   module Associations
-    # Provides the `has_many :views` method to YouTube resources, which
-    # allows to invoke view-related methods, such as .views.
-    # YouTube resources with views are: channels.
+    # Provides methods which allows to access the view count of a resource.
+    #
+    # YouTube resources with view counts are: {Yt::Models::Channel channels}.
     module Views
-      # Return the view count for one specific day.
-      #
+      # @return [Integer, nil] the view count for one specific day.
       # @param [Date or Time or DateTime or String] date The date to obtain
-      # the estimated views for. If String, must be Date-parseable.
-      #
-      # @return [Integer or Nil] The estimated views.
+      #   the views for. If +String+, must be Date-parseable.
       def views_on(date)
         views(from: date, to: date).values.first
       end
 
-      # Return the view count for a range of days.
-      #
-      # @param [Hash] options the range of days to get the views for.
+      # @return [Hash] the view counts for a range of days. Each +key+ is a +Date+
+      #   and each +value+ is an +Integer+ or +nil+, representing the number of views.
+      # @param [Hash] options the range of days to get the view for.
       # @option options [Date or Time or DateTime or String] :since The start
-      # of the days range. If String, must be Date-parseable.
-      # @note options[:since] is aliased as options[:from]
+      #   of the days range. If +String+, must be Date-parseable. Also aliased as *:from*.
       # @option options [Date or Time or DateTime or String] :until The end
-      # of the days range. If String, must be Date-parseable.
-      # @note options[:until] is aliased as options[:to]
-      #
-      # @return [Hash] The view count by day. Each :key is a Date
-      # and each :value is an Integer or nil, representing the number of views.
+      #   of the days range. If +String+, must be Date-parseable. Also aliased as *:to*.
       def views(options = {})
         from = options[:since] || options[:from] || 5.days.ago
         to = options[:until] || options[:to] || 1.day.ago

data/lib/yt/collections/annotations.rb

@@ -4,9 +4,10 @@ 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}.
     # @note Since there is no (authenticable) API endpoint to retrieve
-    #   annotations, only annotations of *public videos* can be retrieved.
+    #   annotations, only annotations of public videos can be retrieved.
     class Annotations < Base
 
     private

data/lib/yt/collections/channels.rb

@@ -4,6 +4,7 @@ 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
 

data/lib/yt/collections/videos.rb

@@ -4,6 +4,7 @@ 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
@@ -27,8 +28,9 @@ module Yt
       end
 
       def videos_params
+        params = {type: :video, maxResults: 50, part: 'snippet', order: 'date'}
         @extra_params ||= {}
-        {type: :video, maxResults: 50, part: 'snippet'}.merge @extra_params
+        params.merge @extra_params
       end
     end
   end

data/lib/yt/models/annotation.rb

@@ -1,13 +1,12 @@
 module Yt
   module Models
     # Provides methods to interact with YouTube annotations.
+    # @note YouTube API V3 does not provide access to video annotations,
+    #   therefore a legacy XML endpoint is used to retrieve annotations.
     # @see https://www.youtube.com/yt/playbook/annotations.html
     class 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
@@ -58,7 +57,7 @@ module Yt
       # @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
+      #   have the timestamp in the region, but in the "data" field
       def starts_after?(seconds)
         timestamps.first > seconds if timestamps.any?
       end
@@ -67,7 +66,7 @@ module Yt
       # @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
+      #   have the timestamp in the region, but in the "data" field
       def starts_before?(seconds)
         timestamps.first < seconds if timestamps.any?
       end

data/lib/yt/models/authentication.rb

@@ -6,11 +6,14 @@ module Yt
 
       # Before your application can access private data using a Google API,
       # it must obtain an access token that grants access to that API.
+      #
       # A single access token can grant varying degrees of access to multiple
       # APIs. A variable parameter called scope controls the set of resources
       # and operations that an access token permits.
+      #
       # After an application obtains an access token, it sends the token to a
       # Google API in an HTTP authorization header.
+      #
       # Access tokens are valid only for the set of operations and resources
       # described in the scope of the token request. For example, if an access
       # token is issued for the Google+ API, it does not grant access to the
@@ -23,12 +26,14 @@ module Yt
       # to a Google API beyond the lifetime of a single access token, it can
       # obtain a refresh token. A refresh token allows your application to
       # obtain new access tokens.
-      # @note Save refresh tokens in secure long-term storage and continue to
+      #
+      # Save refresh tokens in secure long-term storage and continue to
       # use them as long as they remain valid. Limits apply to the number of
       # refresh tokens that are issued per client-user combination, and per
       # user across all clients, and these limits are different. If your
       # application requests enough refresh tokens to go over one of the
       # limits, older refresh tokens stop working.
+      #
       # There is currently a 25-token limit per Google user account.
       # If a user account has 25 valid tokens, the next authentication request
       # succeeds, but quietly invalidates the oldest outstanding token without
@@ -39,7 +44,9 @@ module Yt
 
       # Access tokens have limited lifetimes. If your application needs access
       # to a Google API beyond the lifetime of a single access token, it can
-      # obtain a refresh token. A refresh token allows your application to
+      # obtain a refresh token.
+      #
+      # A refresh token allows your application to
       # obtain new access tokens.
       #
       # @return [Time] the time when access token no longer works.

data/lib/yt/models/rating.rb

@@ -6,7 +6,7 @@ module Yt
     # @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).
+      # @return [Symbol, nil] the rating of a video (if present).
       #  Valid values are: :dislike, :like, :none, :unspecified
       attr_reader :rating
 

data/lib/yt/models/snippet.rb

@@ -3,119 +3,160 @@ require 'yt/models/description'
 module Yt
   module Models
     # Contains basic information about the resource. The details of the snippet
-    # are different for the different types of resources. Resources with a
-    # snippet are: channels, videos, playlists, playlist items.
+    # are different for the different types of resources.
+    #
+    # Resources with a
+    # snippet are: channels, playlists, playlist items and videos.
     # @see https://developers.google.com/youtube/v3/docs/channels#resource
     # @see https://developers.google.com/youtube/v3/docs/videos#resource
+    # @see https://developers.google.com/youtube/v3/docs/playlists#resource
+    # @see https://developers.google.com/youtube/v3/docs/playlistItems#resource
     class Snippet
       def initialize(options = {})
         @data = options[:data]
         @auth = options[:auth]
       end
 
-      # @return [String] the resource’s title.
-      #   For channels: the channel’s title.
-      #   For videos: the video’s title. Has a maximum of 100 characters and
-      #     may contain all valid UTF-8 characters except < and >.
-      #   For playlists: the playlist’s title.
-      #   For playlist items: the item’s title.
+      # @return [String] if the resource is a channel, the channel’s title.
+      # @return [String] if the resource is a playlist, the playlist’s title.
+      # @return [String] if the resource is a playlist item, the item’s title.
+      # @return [String] if the resource is a video, the video’s title. Has a
+      #   maximum of 100 characters and may contain all valid UTF-8 characters
+      #   except < and >.
       def title
         @title ||= @data.fetch 'title', ''
       end
 
-      # @return [Yt::Models::Description] the resource’s description.
-      #   For channels: the channel’s description. Has a maximum of 1000
-      #     characters.
-      #   For videos: the video’s description. Has a maximum of 5000 bytes and
-      #     may contain all valid UTF-8 characters except < and >.
-      #   For playlists: the playlist’s description.
-      #   For playlist items: the item’s description.
+      # @return [Yt::Models::Description] if the resource is a channel, the
+      #   channel’s description. Has a maximum of 1000 characters.
+      # @return [Yt::Models::Description] if the resource is a playlist, the
+      #   playlist’s description.
+      # @return [Yt::Models::Description] if the resource is a playlist item,
+      #   the item’s description.
+      # @return [Yt::Models::Description] if the resource is a video, the
+      #   video’s description. Has a maximum of 5000 bytes and may contain all
+      #   valid UTF-8 characters except < and >.
       def description
         @description ||= Description.new @data.fetch('description', '')
       end
 
-      # @return [Time] the date and time that the resource was published.
-      #   For channels: the date and time that the channel was created.
-      #   For videos: the date and time that the video was published.
-      #   For playlists: the date and time that the playlist was created.
-      #   For playlist items: the date and time that the item was added to the
-      #     playlist.
+      # @return [Time] if the resource is a channel, the date and time that the
+      #  channel was created.
+      # @return [Time] if the resource is a playlist, the date and time that
+      #   the playlist was created.
+      # @return [Time] if the resource is a playlist item, the date and time
+      #   that the item was added to the playlist.
+      # @return [Time] if the resource is a video, the date and time that the
+      #   video was published.
       def published_at
         @published_at ||= Time.parse @data['publishedAt']
       end
 
-      # @param [Symbol or String] size The size of the thumbnail to retrieve.
-      # @return [String or nil] a thumbnail image associated with the resource.
-      #   For channels: sizes correspond to 88x88px (default), 240x240px
-      #     (medium), and 800x800px (high).
-      #   For videos, playlists, playlist items: sizes correspond to 120x90px
-      #     (default), 320x180px (medium), and 480x360px (high).
+      # @param [Symbol, String] size The size of the thumbnail to retrieve.
+      # @return [String] if the resource is a channel and +size+ is +default+,
+      #   the URL of an 88x88px image.
+      # @return [String] if the resource is a playlist, a PlaylistItem or a
+      #    Video and +size+ is +default+, the URL of an 120x90px image.
+      # @return [String] if the resource is a channel and +size+ is +medium+,
+      #   the URL of an 240x240px image.
+      # @return [String] if the resource is a playlist, a PlaylistItem or a
+      #    Video and +size+ is +medium+, the URL of an 320x180px image.
+      # @return [String] if the resource is a channel and +size+ is +high+,
+      #   the URL of an 800x800px image.
+      # @return [String] if the resource is a playlist, a PlaylistItem or a
+      #    Video and +size+ is +high+, the URL of an 480x360px image.
+      # @return [nil] if the +size+ is not +default+, +medium+ or +high+.
       def thumbnail_url(size = :default)
         @thumbnails ||= @data.fetch 'thumbnails', {}
         @thumbnails.fetch(size.to_s, {})['url']
       end
 
-      # @return [String or nil] the ID of the related channel.
-      #   For videos: the ID that YouTube uses to uniquely identify the
-      #     channel that the video was uploaded to.
-      #   For playlists: the ID that YouTube uses to uniquely identify the
-      #     channel that published the playlist.
-      #   For playlist items: the ID that YouTube uses to uniquely identify
-      #     the user that added the item to the playlist.
+      # @return [String] if the resource is a playlist, the ID that YouTube
+      #   uses to uniquely identify the channel that the playlist belongs to.
+      # @return [String] if the resource is a playlist item, the ID that YouTube
+      #   uses to uniquely identify the channel that the playlist belongs to.
+      # @return [String] if the resource is a video, the ID that YouTube uses
+      #   to uniquely identify the channel that the video was uploaded to.
+      # @return [nil] if the resource is a channel.
       def channel_id
         @channel_id ||= @data['channelId']
       end
 
-      # @return [String or nil] the title of the related channel.
-      #   For videos: the title of the channel the video belongs to.
-      #   For playlists: the title of the channel the playlist belongs to.
-      #   For playlist items: the title of the channel the playlist item
-      #     belongs to.
+      # @return [String] if the resource is a playlist, the title of the
+      #   channel that the playlist belongs to.
+      # @return [String] if the resource is a playlist item, the title of the
+      #   channel that the playlist item belongs to.
+      # @return [String] if the resource is a video, the title of the channel
+      #   that the video was uploaded to.
+      # @return [nil] if the resource is a channel.
       def channel_title
         @channel_title ||= @data['channelTitle']
       end
 
-      # @return [Array<Yt::Models::Tag>] A list of associated keyword tags.
-      #   For videos: tags are only visible to the video’s uploader.
-      #   For playlists: keyword tags associated with the playlist.
+      # @return [Array<Yt::Models::Tag>] if the resource is a channel, an
+      #   empty array.
+      # @return [Array<Yt::Models::Tag>] if the resource is a playlist, the
+      #   list of keyword tags associated with the playlist.
+      # @return [Array<Yt::Models::Tag>] if the resource is a playlist item,
+      #   an empty array.
+      # @return [Array<Yt::Models::Tag>] if the resource is a video, the list
+      #   of keyword tags associated with the video.
       def tags
         @tags ||= @data.fetch 'tags', []
       end
 
-      # @return [String or nil] the YouTube video category associated with the
-      #   video (for videos only).
+      # @return [String] if the resource is a video, the YouTube video
+      #   category associated with the video.
+      # @return [nil] if the resource is a channel.
+      # @return [nil] if the resource is a playlist.
+      # @return [nil] if the resource is a playlist item.
       # @see https://developers.google.com/youtube/v3/docs/videoCategories/list
       def category_id
         @category_id ||= @data['categoryId']
       end
 
-      # @return [String or nil] whether the resource is an upcoming/active live
-      #   broadcast. Valid values are: live, none, upcoming (for videos only).
+      # @return [String] if the resource is a video, whether the resource is a
+      #   live broadcast. Valid values are: live, none, upcoming.
+      # @return [nil] if the resource is a channel.
+      # @return [nil] if the resource is a playlist.
+      # @return [nil] if the resource is a playlist item.
       def live_broadcast_content
         @live_broadcast_content ||= @data['liveBroadcastContent']
       end
 
-      # @return [String or nil] the ID that YouTube uses to uniquely identify
-      #   the playlist that the item is in (for playlist items only).
+      # @return [String] if the resource is a playlist item, the ID that
+      #   YouTube uses to uniquely identify the playlist that the item is in.
+      # @return [nil] if the resource is a channel.
+      # @return [nil] if the resource is a playlist.
+      # @return [nil] if the resource is a video.
       def playlist_id
         @playlist_id ||= @data['playlistId']
       end
 
-      # @return [Integer or nil] the order in which the item appears in a
-      #   playlist. The value is zero-based, so the first item has a position
-      #   of 0, the second item of 1, and so forth (for playlist items only).
+      # @return [Integer] if the resource is a playlist item, the order in
+      #   which the item appears in a playlist. The value is zero-based, so the
+      #   first item has a position of 0, the second item of 1, and so forth.
+      # @return [nil] if the resource is a channel.
+      # @return [nil] if the resource is a playlist.
+      # @return [nil] if the resource is a video.
       def position
         @position ||= @data['position'].to_i
       end
 
-      # @return [String or nil] the ID of the video the playlist item
-      #   represents in the playlist (only for playlist items).
+      # @return [String] if the resource is a playlist item, the ID of the
+      #   video the playlist item represents in the playlist.
+      # @return [nil] if the resource is a channel.
+      # @return [nil] if the resource is a playlist.
+      # @return [nil] if the resource is a video.
       def video_id
         @video_id ||= @data.fetch('resourceId', {})['videoId']
       end
 
-      # @return [Yt::Models::Video or nil] the video the playlist item
-      #   represents in the playlist (only for playlist items).
+      # @return [Yt::Models::Video] the video the playlist item represents in
+      #   the playlist.
+      # @return [nil] if the resource is a channel.
+      # @return [nil] if the resource is a playlist.
+      # @return [nil] if the resource is a video.
       def video
         @video ||= Video.new id: video_id, auth: @auth if video_id
       end

data/lib/yt/version.rb

@@ -1,3 +1,3 @@
 module Yt
-  VERSION = '0.7.2'
+  VERSION = '0.7.3'
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: yt
 version: !ruby/object:Gem::Version
-  version: 0.7.2
+  version: 0.7.3
 platform: ruby
 authors:
 - Claudio Baccigalupo
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2014-06-19 00:00:00.000000000 Z
+date: 2014-06-26 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activesupport