thumbtack 0.0.2 → 0.0.3

data/lib/thumbtack/posts.rb

@@ -1,51 +1,63 @@
 # encoding: utf-8
 
 module Thumbtack
-  # Internal: Wraps API calls related to posts.
+  # Wraps API calls related to posts
   class Posts
-    # Internal: Initialize a Posts.
+    # Initialize a Posts
     #
-    # client - A Thumbtack::Client to communicate with the Pinboard API.
+    # @param [Client] client
+    #   client to communicate with the Pinboard API
+    #
+    # @api private
     def initialize(client)
       @client = client
     end
 
-    # Public: The most recent time a bookmark was added, updated, or deleted.
+    # Fetch the most recent time a bookmark was added, updated, or deleted
+    #
+    # @example
+    #   update_time = posts.update
     #
-    # Examples
+    # @return [DateTime]
     #
-    #   update
-    #   # => '2014-06-26T19:01:33Z'
+    # @api public
     #
-    # Returns a DateTime in UTC.
+    # @see https://pinboard.in/api/#posts_update
     def update
       response = @client.get('/posts/update')
       Types::DateTime.from_parameter response.fetch('update_time')
     end
 
-    # Public: Add a bookmark.
-    #
-    # url - A String containing the URL to be bookmarked.
-    # description - A String containing the title of the bookmark.
-    # options - The Hash options to be passed as arguments.
-    #           :extended - A String containing a description of the item.
-    #           :tags     - An Array containing up to 100 tags.
-    #           :dt       - A DateTime containing the creation time for this
-    #                       bookmark.
-    #           :replace  - A Boolean containing whether or not to replace any
-    #                       existing bookmark with this URL.
-    #           :shared   - A Boolean containing whether or not to make the
-    #                       bookmark public.
-    #           :toread   - A Boolean containing whether or not to mark the
-    #                       bookmark as unread.
-    #
-    # Examples
-    #
-    #   add('http://theinternate.com', 'The Internate')
-    #   add('http://theinternate.com', 'The Internate', tags: ['best', 'ruby'])
-    #
-    # Returns the Posts instance.
-    def add(url, description, options = {})
+    # Add a bookmark
+    #
+    # @example
+    #   posts.add(url, description, tags: ['one', 'two', 'three'])
+    #
+    # @param [String] url
+    #   the URL of the bookmark
+    # @param [String] description
+    #   title of the bookmark
+    # @param [Hash] options
+    #   options for the bookmark addition
+    # @option options [String] :extended
+    #   a description of the bookmark
+    # @option options [Array[String]] :tags
+    #   a list of up to 100 tags
+    # @option options [DateTime] :dt
+    #   the creation time for this bookmark
+    # @option options [Boolean] :replace
+    #   if true, replace any existing bookmark with the same URL
+    # @option options [Boolean] :shared
+    #   if true, make the bookmark public
+    # @option options [Boolean] :toread
+    #   if true, mark the bookmark unread
+    #
+    # @return [self]
+    #
+    # @api public
+    #
+    # @see https://pinboard.in/api/#posts_add
+    def add(url, description, options = EMPTY_HASH)
       parameters = Specification.new(
         url: Types::URL,
         description: Types::Text,
@@ -60,38 +72,47 @@ module Thumbtack
       self
     end
 
-    # Public: Delete a bookmark.
+    # Delete a bookmark
+    #
+    # @example
+    #   posts.delete(url)
     #
-    # url - A String containing the URL of the bookmark to delete.
+    # @param [String] url
+    #   the URL of the bookmark to delete
     #
-    # Examples
+    # @return [self]
     #
-    #   delete('http://delicio.us')
+    # @api public
     #
-    # Returns the Posts instance
+    # @see https://pinboard.in/api/#posts_delete
     def delete(url)
       parameters = Specification.new(url: Types::URL).parameters(url: url)
       @client.get('/posts/delete', parameters)
       self
     end
 
-    # Public: Return one or more posts matching the arguments.
+    # Fetch one or more bookmarks
     #
-    # options - The Hash options to be passed as arguments.
-    #          :tag  - An Array containing a up to three tags to filter by.
-    #          :dt   - A DateTime containing the date when the results were
-    #                  bookmarked.
-    #          :url  - A String containing the URL for the the bookmark.
-    #          :meta - A Boolean indicating whether or not to include a change
-    #                  detection signature.
+    # @example
+    #   bookmarks = posts.get(tag: ['one', 'two', 'three'])
     #
-    # Examples
+    # @param [Hash] options
+    #   options to filter the results by
+    # @option options [Array<String>] :tag
+    #   up to three tags to filter by
+    # @option options [DateTime] :dt
+    #   which day the results were bookmarked
+    # @option options [String] :url
+    #   the URL for this bookmark
+    # @option options [Boolean] :meta
+    #   if true, include the change detection signature in the results
     #
-    #   get(tag: 'webdev', meta: 'yes')
-    #   get(url: 'http://www.pinboard.in')
+    # @return [Array<Post>]
     #
-    # Returns a list of Post instances.
-    def get(options = {})
+    # @api public
+    #
+    # @see https://pinboard.in/api/#posts_get
+    def get(options = EMPTY_HASH)
       parameters = Specification.new(
         tag: Types::Tags,
         dt: Types::DateTime,
@@ -101,19 +122,24 @@ module Thumbtack
       posts_from @client.get('/posts/get', parameters)
     end
 
-    # Public: Return a list of the most recent posts.
+    # List the most recent bookmarks
+    #
+    # @example
+    #   bookmarks = posts.recent(tag: ['one', 'two', 'three'], count: 25)
     #
-    # options - The Hash options to be passed as arguments.
-    #          :tag   - An Array containing a up to three tags to filter by.
-    #          :count - An Integer of the number of results to return. Default
-    #                   is 15, maximum is 100.
+    # @param [Hash] options
+    #   options to filter the results by
+    # @option options [Array<String>] :tag
+    #   up to three tags to filter by
+    # @option options [Integer] :count
+    #   the number of results to return
     #
-    # Examples
+    # @return [Array<Post>]
     #
-    #   recent(tag: 'webdev', count: 25)
+    # @api public
     #
-    # Returns a list of Post instances.
-    def recent(options = {})
+    # @see https://pinboard.in/api/#posts_recent
+    def recent(options = EMPTY_HASH)
       parameters = Specification.new(
         tag: Types::Tags,
         count: Types::Integer
@@ -121,20 +147,32 @@ module Thumbtack
       posts_from @client.get('/posts/recent', parameters)
     end
 
-    # Public: Return all posts in the account.
-    #
-    # options - The Hash options to be passed as arguments.
-    #          :tag     - A String containing a list of up to three tags to
-    #                     filter by.
-    #          :start   - An Integer offset value. Default is 0.
-    #          :results - An Integer of the number of results to return.
-    #          :fromdt  - Filter results to posts created after this DateTime.
-    #          :todt    - Filter results to posts created before this DateTime.
-    #          :meta    - A Boolean containing whether or not to include a
-    #                     change detection signature.
-    #
-    # Returns a list of Posts instances
-    def all(options = {})
+    # List all bookmarks
+    #
+    # @example
+    #   posts.all(todt: yesterday, meta: true, tag: ['one', 'two', 'three'])
+    #
+    # @param [Hash] options
+    #   options to filter the results by
+    # @option options [Array<String>] :tag
+    #   up to three tags to filter by
+    # @option options [Array<String>] :start
+    #   an offset value
+    # @option options [Array<String>] :results
+    #   number of results to return
+    # @option options [DateTime] :fromdt
+    #   limit results to those created after this time
+    # @option options [DateTime] :todt
+    #   limit results to those created before this time
+    # @option options [Boolean] :meta
+    #   if true, include the change detection signature in the results
+    #
+    # @return [Array<Post>]
+    #
+    # @api public
+    #
+    # @see https://pinboard.in/api/#posts_all
+    def all(options = EMPTY_HASH)
       parameters = Specification.new(
         tag: Types::Tags,
         start: Types::Integer,
@@ -147,31 +185,49 @@ module Thumbtack
       results.map { |post_hash| Post.from_hash(post_hash) }
     end
 
-    # Public: Return a list of popular and recommended tags for a URL.
+    # List popular and recommended tags for a URL
+    #
+    # @example
+    #   suggestion = posts.suggest(url)
     #
-    # url - A String containing a URL to fetch suggested tags for.
+    # @param [String] url
+    #   URL to fetch suggested tags for
     #
     # Returns a Hash with two entries, :popular is a list of popular tags,
     # :recommended is a list of recommended tags.
+    #
+    # @return [Array<Suggestion>]
+    #
+    # @api public
+    #
+    # @see https://pinboard.in/api/#posts_suggest
     def suggest(url)
       parameters = Specification.new(url: Types::URL).parameters(url: url)
-      result = @client.get('/posts/suggest', parameters)
-      { popular: result.fetch('popular'),
-        recommended: result.fetch('recommended') }
+      Suggestion.from_array(@client.get('/posts/suggest', parameters))
     end
 
-    # Public: Return a list dates with the count of posts made at each date.
+    # List dates with the number of bookmarks created on each
+    #
+    # @example
+    #   dates = posts.dates(tag: ['one', 'two', 'three'])
+    #
+    # @param [Hash] options
+    #   options to filter the results by
+    # @option options [Array<String>] :tag
+    #   up to three tags to filter by
+    #
+    # @return [Hash{Date => Integer}]
+    #   dates on which bookmarks were created associated with the number of
+    #   bookmarks created on that date
     #
-    # options - The Hash options to be passed as arguments
-    #          :tag - An Array containing a up to three tags to filter by.
+    # @api public
     #
-    # Returns a Hash of Strings => Integer entries. The Strings contain a date
-    # and the Integer is the count of posts made on that date.
-    def dates(options = {})
+    # @see https://pinboard.in/api/#posts_dates
+    def dates(options = EMPTY_HASH)
       parameters = Specification.new(tag: Types::Tags).parameters(options)
       response = @client.get('/posts/dates', parameters)
       Hash[
-        response.fetch('dates', {}).map do |date, count|
+        response.fetch('dates', EMPTY_HASH).map do |date, count|
           [Types::Date.from_parameter(date), count.to_i]
         end
       ]
@@ -180,7 +236,9 @@ module Thumbtack
     private
 
     def posts_from(response)
-      response.fetch('posts', []).map { |post_hash| Post.from_hash(post_hash) }
+      response.fetch('posts', EMPTY_ARRAY).map do |post_hash|
+        Post.from_hash(post_hash)
+      end
     end
   end
 end

data/lib/thumbtack/specification.rb

@@ -1,23 +1,27 @@
 # encoding: utf-8
 
 module Thumbtack
-  # Internal: Validates and translates user-provided parameters to their
-  # Pinboard-supported equivalents
+  # Validates and translates user-provided parameters to their Pinboard
+  # supported equivalents
+  #
+  # @api private
   class Specification
-
-    # Create a new Specification.
+    # Initialize a Specification
     #
-    # type_handlers - A Hash mapping parameter names to their type handlers.
+    # @param [Hash{Symbol => Type}] type_handlers
+    #   a map of parameter names to their type handlers
     def initialize(type_handlers)
       @type_handlers = type_handlers
     end
 
     # Validate and translate user-provided parameters to their
-    # Pinboard-supported equivalents.
+    # Pinboard-supported values
     #
-    # arguments - A Hash mapping parameter names to their user-provided values.
+    # @param [Hash{Symbol => Object}] arguments
+    #   parameter names associated with their values
     #
-    # Returns the parameters translated to their Pinboard equivalents.
+    # @return [Hash{Symbol => Object}]
+    #   parameter names associated with translations to their Pinboard values
     def parameters(arguments)
       Hash[
         arguments.map do |name, value|

data/lib/thumbtack/suggestion.rb

@@ -0,0 +1,59 @@
+# encoding: utf-8
+
+module Thumbtack
+  # Represents a suggestion
+  #
+  # @api public
+  class Suggestion
+    # The key associated with popular tags
+    #
+    # @api private
+    POPULAR_KEY = 'popular'.freeze
+
+    # The key associated with suggested tags
+    #
+    # @api private
+    RECOMMENDED_KEY = 'recommended'.freeze
+
+    # A list of popular tags for URL
+    #
+    # @return [Array<String>]
+    #
+    # @api public
+    attr_reader :popular
+
+    # A list of recommended tags for the URL
+    #
+    # @return [Array<String>]
+    #
+    # @api public
+    attr_reader :recommended
+
+    # Initialize a Suggestion
+    #
+    # @param [Hash] attrs
+    #   Suggestion attributes
+    #
+    # @api private
+    def initialize(attrs = EMPTY_HASH)
+      @popular = attrs.fetch(:popular)
+      @recommended = attrs.fetch(:recommended)
+    end
+
+    # Creates a new Suggestions from an Array of Hashes
+    #
+    # @param [Array<Hash{String => Array<String>}>] array
+    #   Suggestions attributes
+    #
+    # @return [Suggestion]
+    #
+    # @api private
+    # @see Client#get
+    def self.from_array(array)
+      popular = array.find { |hash| hash.key?(POPULAR_KEY) }
+      recommended = array.find { |hash| hash.key?(RECOMMENDED_KEY) }
+      new(popular: popular.fetch(POPULAR_KEY, EMPTY_ARRAY),
+          recommended: recommended.fetch(RECOMMENDED_KEY, EMPTY_ARRAY))
+    end
+  end
+end

data/lib/thumbtack/tags.rb

@@ -1,38 +1,68 @@
 # encoding: utf-8
 
 module Thumbtack
-  # Internal: Wraps API calls related to tags.
+  # Wraps API calls related to tags
   class Tags
-    # Internal: Creates a new Tags.
+    # Initialize a Tags
     #
-    # client - a Thumbtack::Client to communicate with the Pinboard API.
+    # @param [Client] client
+    #   client to communicate with the Pinboard API
+    #
+    # @api private
     def initialize(client)
       @client = client
     end
 
-    # Public: Returns a list of the user's tags with their counts.
+    # List tags with their counts
+    #
+    # @example
+    #   tag_counts = tags.get
+    #
+    # @return [Hash{String => Integer}]
+    #   tags associated with the number of times they have been used
+    #
+    # @api public
+    #
+    # @see https://pinboard.in/api/#tags_get
     def get
       response = @client.get('/tags/get')
       Hash[response.map { |tag, count| [tag, count.to_i] }]
     end
 
-    # Public: Delete a tag.
+    # Delete a tag
+    #
+    # @example
+    #   tags.delete(tag)
     #
-    # tag - A String containing the tag to delete.
+    # @param [String] tag
+    #   the tag to delete
     #
-    # Returns the Tags instance.
+    # @return [self]
+    #
+    # @api public
+    #
+    # @see https://pinboard.in/api/#tags_delete
     def delete(tag)
       parameters = Specification.new(tag: Types::Tags).parameters(tag: tag)
       @client.get('/tags/delete', parameters)
       self
     end
 
-    # Public: Rename a tag.
+    # Rename a tag
+    #
+    # @example
+    #   tags.rename(old, new)
+    #
+    # @param [String] old
+    #   the tag to be renamed
+    # @param [String] new
+    #   the new name for the tag
+    #
+    # @return [self]
     #
-    # old - A String containing the tag to be renamed.
-    # new - A String containing the new name for the tag.
+    # @api public
     #
-    # Returns the Tags instance.
+    # @see https://pinboard.in/api/#tags_rename
     def rename(old, new)
       parameters = Specification.new(
         old: Types::Tags,