thumbtack 0.0.2 → 0.0.3

data/lib/thumbtack/types.rb

@@ -1,10 +1,11 @@
 # encoding: utf-8
 
 module Thumbtack
-  # Handlers for each of the data types in the Pinboard API. See
-  # https://pinboard.in/api/#data
+  # Handlers for each of the data types in the Pinboard API
+  #
+  # @see https://pinboard.in/api/#data
   module Types
-    # Internal: Raised when given an invalid argument
+    # Raised when given an argument that does not satisfy the type constraints
     class ValidationError < StandardError; end
   end
 end

data/lib/thumbtack/types/boolean.rb

@@ -2,15 +2,20 @@
 
 module Thumbtack
   module Types
-    # Internal: Handles conversion and validation of Boolean types to the 'yes'
-    # and 'no' parameters supported by the Pinboard API.
+    # Handles conversion and validation of Booleans to the 'yes'
+    # and 'no' parameters supported by Pinboard
+    #
+    # @api private
     class Boolean
-      # Validate something is a Boolean parameter.
+      # Validate a value is a boolean parameter
       #
-      # value - A Boolean to validate.
+      # @param [Boolean] value
+      #   the value to validate
       #
-      # Returns nothing.
-      # Raises Types::ValidationError if the value is not true or false
+      # @return [undefined]
+      #
+      # @raise [Types::ValidationError]
+      #   if the value is not true or false
       def self.validate(value)
         case value
         when TrueClass, FalseClass
@@ -20,11 +25,13 @@ module Thumbtack
         end
       end
 
-      # Convert a Boolean value to a parameter acceptable to the Pinboard API.
+      # Convert a boolean value to a parameter acceptable to Pinboard
       #
-      # value - A Boolean to convert.
+      # @param [Boolean] value
+      #   the value to convert
       #
-      # Returns 'yes' or 'no'
+      # @return [String]
+      #   'yes' if value is true, 'no' otherwise
       def self.to_parameter(value)
         case value
         when TrueClass
@@ -34,11 +41,12 @@ module Thumbtack
         end
       end
 
-      # Convert a parameter from the Pinboard API to a Ruby Boolean.
+      # Convert a parameter from Pinboard to a boolean value
       #
-      # parameter - A String containing 'yes' or 'no'.
+      # @param [String] parameter
+      #   Either 'yes' or 'no'
       #
-      # Returns true or false.
+      # @return [Boolean]
       def self.from_parameter(parameter)
         case parameter
         when 'yes'

data/lib/thumbtack/types/date.rb

@@ -2,21 +2,25 @@
 
 module Thumbtack
   module Types
-    # Internal: Handles conversion and validation of Date types to the String
-    # parameters supported by the Pinboard API.
+    # Handles conversion and validation of Dates to parameters supported by
+    # Pinboard
+    #
+    # @api private
     class Date
       # The earliest allowable date
       EARLIEST = ::Date.new(1, 1, 1)
       # The latest allowable date
       LATEST = ::Date.new(2100, 1, 1)
 
-      # Validate a Date.
+      # Validate a date
       #
-      # value - The Date to validate.
+      # @param [Date] value
+      #   the date to validate
       #
-      # Returns nothing.
-      # Raises Types::ValidationError if the date is not between 0001-01-01 and
-      # 2100-01-01.
+      # @return [undefined]
+      #
+      # @raise [Types::ValidationError]
+      #   if the date is not between 0001-01-01 and 2100-01-01
       def self.validate(value)
         unless value > EARLIEST && value < LATEST
           fail ValidationError,
@@ -25,20 +29,23 @@ module Thumbtack
         self
       end
 
-      # Convert a Date value to a parameter acceptable to the Pinboard API.
+      # Convert a date to a parameter acceptable to Pinboard
       #
-      # value - The Date to convert.
+      # @param [Date] value
+      #   the date to convert
       #
-      # Returns a String containing the date with format yyyy-mm-dd.
+      # @return [String]
+      #   the date with format yyyy-mm-dd
       def self.to_parameter(value)
         value.xmlschema
       end
 
-      # Convert a parameter from the Pinboard API to a Ruby Date.
+      # Convert a parameter from Pinboard to a date
       #
-      # parameter - A String of the date formatted yyyy-mm-dd.
+      # @param [String] parameter
+      #   the date with format yyyy-mm-dd
       #
-      # Returns a Date.
+      # @return [Date]
       def self.from_parameter(parameter)
         ::Date.xmlschema(parameter)
       end

data/lib/thumbtack/types/date_time.rb

@@ -2,23 +2,27 @@
 
 module Thumbtack
   module Types
-    # Handles conversion and validation of DateTime types to the String
-    # parameters supported by the Pinboard API.
+    # Handles conversion and validation of DateTimes to parameters supported by
+    # Pinboard
+    #
+    # @api private
     class DateTime
       # The earliest allowable time
       EARLIEST = ::DateTime.new(1, 1, 1)
       # The latest allowable time
       LATEST = ::DateTime.new(2100, 1, 1)
-      # The date format of the Pinboard API
+      # Pinboard's date format
       FORMAT = '%Y-%m-%dT%H:%M:%SZ'.freeze
 
-      # Validate something is a valid DateTime parameter.
+      # Validate a time
       #
-      # value - The DateTime to validate.
+      # @param [DateTime] value
+      #   The time to validate
       #
-      # Returns nothing.
-      # Raises Types::ValidationError if the time is not between
-      # 0001-01-01 00:00:00 and 2100-01-01 00:00:00.
+      # @return [undefined]
+      #
+      # @raise [Types::ValidationError]
+      #   if the time is not between 0001-01-01 00:00:00 and 2100-01-01 00:00:00
       def self.validate(value)
         unless value > EARLIEST && value < LATEST
           fail ValidationError,
@@ -27,20 +31,23 @@ module Thumbtack
         self
       end
 
-      # Convert a DateTime value to a parameter acceptable to the Pinboard API.
+      # Convert a time to a parameter acceptable to Pinboard
       #
-      # value - The DateTime to convert.
+      # @param [DateTime] value
+      #   the time to convert
       #
-      # Returns a String containing the date with format yyyy-mm-ddTHH:MM:SSZ.
+      # @return [String]
+      #   the time formatted yyyy-mm-ddTHH:MM:SSZ.
       def self.to_parameter(value)
         value.strftime(FORMAT)
       end
 
-      # Convert a parameter from the Pinboard API to a Ruby DateTime.
+      # Convert a parameter from Pinboard to a datetime value
       #
-      # parameter - A String of the date formatted yyyy-mm-ddTHH:MM:SSZ.
+      # @param [String] parameter
+      #   the time formatted yyyy-mm-ddTHH:MM:SSZ
       #
-      # Returns a DateTime.
+      # @return [DateTime]
       def self.from_parameter(parameter)
         ::DateTime.strptime(parameter)
       end

data/lib/thumbtack/types/identity.rb

@@ -2,22 +2,27 @@
 
 module Thumbtack
   module Types
-    # Internal: An abstract type handler
+    # An abstract type handler with no conversion or validation
+    #
+    # @api private
     class Identity
-
-      # Any value passed is valid.
+      # Any value passed is valid
       #
-      # Returns nothing.
+      # @return [undefined]
       def self.validate(*)
         self
       end
 
-      # Return any value passed to this without conversion.
+      # Value is returned unconverted
+      #
+      # @return [value]
       def self.to_parameter(value)
         value
       end
 
-      # Return any value passed to this without conversion.
+      # Parameter is returned unconverted
+      #
+      # @return [parameter]
       def self.from_parameter(parameter)
         parameter
       end

data/lib/thumbtack/types/integer.rb

@@ -2,20 +2,24 @@
 
 module Thumbtack
   module Types
-    # Internal: Handles validation of Integer types as the values supported by
-    # the Pinboard API.
+    # Handles validation of Integer types as the values supported by Pinboard
+    #
+    # @api private
     class Integer < Identity
-      # The minimum allowable integer.
+      # The minimum allowable integer
       MIN = 0
-      # The maximum allowable integer.
+      # The maximum allowable integer
       MAX = 2**32
 
-      # Validate something is a valid integer parameter.
+      # Validate something is a valid integer parameter
       #
-      # value - An integer to validate.
+      # @param [Integer] value
+      #   the integer to validate
       #
-      # Returns nothing.
-      # Raises Types::ValidationError if the value is not between 0 and 2^32.
+      # @return [undefined]
+      #
+      # @raise [Types::ValidationError]
+      #   if the value is not between 0 and 2^32
       def self.validate(value)
         unless value >= MIN && value <= MAX
           fail ValidationError, "#{value} must be in range 0..2^32"

data/lib/thumbtack/types/md5.rb

@@ -2,21 +2,24 @@
 
 module Thumbtack
   module Types
-    # Internal: Handles validation of MD5 types as the values supported by the
-    # Pinboard API.
+    # Handles validation of MD5 types as the values supported by Pinboard
+    #
+    # @api private
     class MD5 < Identity
-      # The length of an MD5 value.
+      # The length of an MD5 value
       LENGTH = 32
-      # The valid characters in an MD5 value.
+      # The valid characters in an MD5 value
       CHARACTERS = '0123456789abcdf'.freeze
 
-      # Validate something is a valid MD5 parameter.
+      # Validate a string is a valid MD5 parameter
       #
-      # value - A String containing the MD5 to validate.
+      # @param [String] value
+      #   the MD5 to validate
       #
-      # Returns nothing.
-      # Raises Types::ValidationError if the value is not a 32 character
-      # hexadecimal MD5 hash.
+      # @return [undefined]
+      #
+      # @raise [Types::ValidationError]
+      #   if the value is not a 32 character hexadecimal MD5 hash
       def self.validate(value)
         unless value.length == 32 &&
             value.each_char.all? { |char| CHARACTERS.include?(char) }

data/lib/thumbtack/types/tags.rb

@@ -2,24 +2,27 @@
 
 module Thumbtack
   module Types
-    # Internal: Handles validation of tag lists as the values supported by the
-    # Pinboard API.
+    # Handles conversion and validation of tag lists to values supported by
+    # Pinboard
+    #
+    # @api private
     class Tags
-      # The maximum tag length.
+      # The maximum tag length
       MAXIMUM_LENGTH = 255
-      # Tags cannot have commas.
+      # Tags cannot have commas
       INVALID_CHARACTER = ','.freeze
-      # Tag parameters are separated by spaces.
+      # Tag parameters are separated by spaces
       SEPARATOR = ' '.freeze
 
-      # Validate a tags value.
+      # Validate a tags value
       #
-      # value - A String containing a single tag or an Array containing many
-      #         tags.
+      # @param [String, Array<String>] value
+      #   a single tag or an array of many tags
       #
-      # Returns nothing.
-      # Raises Types::ValidationError if any tag contains commas or are longer
-      # than 255 characters.
+      # @return [undefined]
+      #
+      # @raise [Types::ValidationError]
+      #   if any tag contains commas or are longer than 255 characters
       def self.validate(value)
         Array(value).each do |tag|
           unless tag.length < MAXIMUM_LENGTH && !tag.include?(INVALID_CHARACTER)
@@ -30,21 +33,23 @@ module Thumbtack
         self
       end
 
-      # Convert a tag value to a parameter acceptable to the Pinboard API.
+      # Convert a tag value to a parameter acceptable to Pinboard
       #
-      # value - A String containing a single tag or an Array containing many
-      #         tags.
+      # @param [String, Array<String>] value
+      #   a single tag or an array of many tags
       #
-      # Returns a String containing the tags, space-separated.
+      # @return [String]
+      #   space-separated list of tags
       def self.to_parameter(value)
         Array(value).map(&:strip).join(SEPARATOR)
       end
 
-      # Convert a parameter from the Pinboard API to an Array of tags.
+      # Convert a parameter from Pinboard to a list of tags
       #
-      # parameter - A String containing space-separated tags.
+      # @param [String] parameter
+      #   space-separated list of tags
       #
-      # Returns an Array of tags.
+      # @return [Array<String>]
       def self.from_parameter(parameter)
         parameter.split(SEPARATOR)
       end

data/lib/thumbtack/types/text.rb

@@ -2,18 +2,22 @@
 
 module Thumbtack
   module Types
-    # Internal: Handles validation of text values as supported by Pinboard.
+    # Handles validation of text values as supported by Pinboard
+    #
+    # @api private
     class Text < Identity
-      # Maximum length of a text value.
+      # Maximum length of a text value
       MAXIMUM_LENGTH = 65_536
 
-      # Validate text.
+      # Validate text
       #
-      # value - A String containing the text to validate.
+      # @param [String] value
+      #   text to validate
       #
-      # Returns nothing.
-      # Raises Types::ValidationError if the value is longer than 65536
-      # characters.
+      # @return [undefined]
+      #
+      # @raise [Types::ValidationError]
+      #   if the value is longer than 65536 characters
       def self.validate(value)
         unless value.length <= MAXIMUM_LENGTH
           fail ValidationError,

data/lib/thumbtack/types/title.rb

@@ -2,18 +2,22 @@
 
 module Thumbtack
   module Types
-    # Internal: Handles validation of title values as supported by Pinboard.
+    # Handles validation of title values as supported by Pinboard
+    #
+    # @api private
     class Title < Identity
-      # Maximum length of a title value.
+      # Maximum length of a title value
       MAXIMUM_LENGTH = 255
 
-      # Validate a title.
+      # Validate a title
       #
-      # value - A String containing the title to validate.
+      # @param [String] value
+      #   the title to validate
       #
-      # Returns nothing.
-      # Raises Types::ValidationError if the value is longer than 255
-      # characters.
+      # @return [undefined]
+      #
+      # @raise [Types::ValidationError]
+      #   if the value is longer than 255 characters
       def self.validate(value)
         unless value.length <= MAXIMUM_LENGTH
           fail ValidationError,

data/lib/thumbtack/types/url.rb

@@ -2,18 +2,23 @@
 
 module Thumbtack
   module Types
-    # Internal: Handles validation of URL values as supported by Pinboard.
+    # Handles validation of URL values as supported by Pinboard
+    #
+    # @api private
     class URL < Identity
-      # Valid URL schemes.
+      # Valid URL schemes
       VALID_SCHEMES = %w(http https javascript mailto ftp file feed).freeze
 
-      # Validate a URL.
+      # Validate a URL
       #
-      # value - A String containing the URL to validate.
+      # @param [String] value
+      #   the URL to validate
       #
-      # Returns nothing.
-      # Raises Types::ValidationError if the URL's scheme isn't one of http,
-      # https, javascript, mailto, ftp, file, or feed.
+      # @return [undefined]
+      #
+      # @raise [Types::ValidationError]
+      #   if the URL's scheme isn't one of http, https, javascript, mailto, ftp,
+      #   file, or feed
       def self.validate(value)
         unless VALID_SCHEMES.include? URI(value).scheme
           fail ValidationError,