Added pending documentation, changed version practice

CHANGELOG.md

@@ -1,4 +1,4 @@
-## [In git](https://github.com/elgalu/twitter_anonymous_client/compare/v0.0.1...HEAD)
+## [In git](https://github.com/elgalu/twitter_anonymous_client/compare/v0.0.2...HEAD)
 
 ### New Features
 * n/a
@@ -9,6 +9,17 @@
 ### Chores
 * n/a
 
+## [v0.0.2](https://github.com/elgalu/twitter_anonymous_client/tree/v0.0.2)
+
+### New Features
+* n/a
+
+### Bugfixes
+* n/a
+
+### Chores
+* Added documentation. (Leo Gallucci)
+
 ## [v0.0.1](https://github.com/elgalu/twitter_anonymous_client/tree/v0.0.1)
 
 ## First gem release

README.md

@@ -20,7 +20,7 @@ Twitter public (anonymous) client for old v1.0 API just to retrieve the last N u
 require 'twitter_anonymous_client'
 
 tweets = Twitter::Client.new.user_timeline('elgalu', count: 1)
-elgalu = tweets.first #=>  #<Twitter::Tweet:0x00.. @id="3076....
+elgalu = tweets.first #=>  #<Twitter::Tweet:0x00.. @id="3076....>
 elgalu.text #=> "Console Ruby debug is easy - Leo Gallucci's blog http://t.co/JUpUdyf5ts"
 ```
 

lib/twitter/api/timelines.rb

@@ -3,14 +3,18 @@
 
 module Twitter
   module API
-    # @note Inspired from gems\twitter-4.5.0\spec\twitter\api\timelines_spec.rb
+    # @note Inspired from twitter-4.5.0/spec/twitter/api/timelines_spec.rb
     module Timelines
 
-      # Get some user timeline by screen name
+      # Get some user timeline by screen name (last statuses)
       #
-      # @example
-      #   user_timeline('DolarBlue', count: 1)
+      # @param [String] screen_name the twitter user slug
+      # @param [Hash] opts the options to retrieve the statuses
+      # @option opts [Integer] :count The number of statuses to retrieve
       #
+      # @example
+      #   Twitter::Client.new.user_timeline('DolarBlue', count: 1)
+      #   #=> [#<Twitter::Tweet:0x011.. @id="308609..., @text="Dolar Paralelo: $7,84.....
       def user_timeline(screen_name, opts)
         # Sanitize arguments
         count = opts[:count] || 1
@@ -22,6 +26,8 @@ def user_timeline(screen_name, opts)
 
       private
 
+      # (see #user_timeline)
+      # @private
       def get_user_timeline_results(screen_name, count)
         path = "statuses/user_timeline.json"
         qry = []

lib/twitter/client.rb

@@ -6,14 +6,24 @@
 require 'json'
 
 module Twitter
-  # @note Inspired from gems\twitter-4.5.0\spec\twitter\tweet_spec.rb
+  # @note Inspired from twitter-4.5.0/spec/twitter/tweet_spec.rb
   class Client
     ConnectionError = Class.new(StandardError)
 
     include Twitter::API::Timelines
 
-    # Perform an HTTP GET request
-    # qry = [['slug', 'élgalu'], ['age', '31']]
+    # Perform an HTTP get request against Twitter API then parse the result
+    #
+    # @param [String] path the relative path to twitter API
+    # @param [Array<Array<(String, String)>>] qry a nested array used to build the http query string
+    #
+    # @return [Array<Hash>] a collection of twitter response object, for example tweets
+    #
+    # @example
+    #   path = "statuses/user_timeline.json"
+    #   qry = [['screen_name', 'elgalu'], ['count', '1']]
+    #   Twitter::Client.new.get(path, qry)
+    #   #=> [{"created_at"=>"Fri Mar 01 21:42:19 +0000 2013", "id"=>30760....
     def get(path, qry=[])
       uri = build_uri(path, qry)
       begin
@@ -28,15 +38,30 @@ def get(path, qry=[])
 
     private
 
+    # Builds an URI object out of a path and a query string appending twitter endpoint and api version
+    #
+    # @param (see #get)
+    #
+    # @return [URI] parsed ready url
+    #
+    # @private
     def build_uri(path, qry=[])
       query = URI.encode_www_form(qry)
       path.chomp!('/')
       path.sub!(/^\//, '')
-      base = Twitter::Default::ENDPOINT
-      ver  = Twitter::Default::API_VERSION
+      base = Twitter::Default.endpoint
+      ver  = Twitter::Default.api_version
       URI.parse("#{base}/#{ver}/#{path}?#{query}")
     end
 
+    # Output connection related errors and terminates execusion
+    #
+    # @param [URI] uri the uri from which will use the full url
+    # @param [String] msg the custom error message
+    #
+    # @raise [ConnectionError] always, with url and message
+    #
+    # @private
     def pute(uri, msg)
       raise ConnectionError.new("#{msg}\nRequest: #{uri.to_s}\n")
     end

lib/twitter/default.rb

@@ -4,5 +4,20 @@ module Default
       ENDPOINT = 'http://api.twitter.com'
       API_VERSION = '1'
     end
+
+    class << self
+      # @note This is configurable in case you want to use a Twitter-compatible endpoint.
+      # @see https://github.com/sferik/twitter/blob/01e2781e4a78137ca4e5e6d3e4faf2552ee9ec76/lib/twitter/default.rb#L78
+      # @return [String]
+      def endpoint
+        ENDPOINT
+      end
+
+      # @note Should be stuck with no-oauth twitter versions (public API)
+      # @return [String]
+      def api_version
+        API_VERSION
+      end
+    end
   end
 end

lib/twitter/tweet.rb

@@ -3,11 +3,20 @@
 require 'date'
 
 module Twitter
-  # @note Inspired from gems\twitter-4.5.0\lib\twitter\api\timelines.rb
+  # @note Inspired from twitter-4.5.0/lib/twitter/api/timelines.rb
   class Tweet
     # Class Methods
     class << self
-      # Transform json array into a collection of tweets
+      # Transform a json array into a collection of tweets
+      #
+      # @param [Array<Hash>] ary the json twitter results turned into an array of hashes
+      #
+      # @return [Array<Tweet>] the array of Tweets normalized objects
+      #
+      # @example
+      #   ary = [{'created_at'=>'2013-02-28', 'id'=>3, 'text'=>'hello world'}]
+      #   Twitter::Tweet.build_tweets(ary)
+      #   #=> [#<Twitter::Tweet:0x07.. @id="3", @text="hello world", @created_at=#<DateTime: 2013-02-27>>]
       def build_tweets(ary)
         tweets = ary.map do |tweet|
           args = { id:         tweet['id'],

lib/twitter_anonymous_client/version.rb

@@ -1,3 +1,9 @@
 module TwitterAnonymousClient
-  VERSION = "0.0.1"
+  # Four digits version:
+  # "a.b.c.d"
+  # The first 2 digits (a,b) are the Twitter API version used, in this case verion 1.
+  # The last 2 digits (c,d) are this gem version.
+  #   c is a major update or any update that breaks this gem API.
+  #   d is minor or bugfix update.
+  VERSION = "1.0.0.0"
 end

twitter_anonymous_client.gemspec

@@ -33,6 +33,6 @@ Gem::Specification.new do |spec|
   spec.add_development_dependency "yard", ">= 0.8.5.2"
   spec.add_development_dependency "simplecov", ">= 0.7.1"
   spec.add_development_dependency 'coveralls', '>= 0.5.8'
-  spec.add_development_dependency 'webmock', '>= 1.10.1'
+  spec.add_development_dependency 'webmock', '>= 1.11'
 
 end