chronic 0.6.5 → 0.8.0

data/.gitignore

@@ -3,3 +3,4 @@ pkg
 rdoc
 .yardoc
 doc
+tags

data/HISTORY.md

@@ -1,3 +1,28 @@
+# 0.8.0 / 2012-09-16
+
+* Support parsing "<ordinal> of this month" (#109)
+* Support parsing ISO 8601 format (#115)
+* Support parsing "on <day>" without a timestamp (#117)
+* Fix time parsing regexp (#125)
+* Support time when parsing dd-mm-yyy <time> (#126)
+* Allow anchor handler to accept any separators (at, on) (#128)
+* Support parsing EXIF date format (#112)
+* Start using minitest for testing
+* Ensure periods are interpreted as colons (#81).
+* Support month/day and day/month parsing (#59).
+* Support day(scalar)-month(name)-year(scalar) (#99).
+* Handle text starting with 'a' or 'an' (#101, @steveburkett).
+* Ensure post medium timestamps are correctly formatted (#89)
+
+# 0.6.7 / 2012-01-31
+
+* Handle day, month names with scalar day and year (Joe Fiorini)
+* Ensure 31st parses correctly with day names (Joe Fiorini)
+
+# 0.6.6 / 2011-11-23
+
+* `Chronic.parse('thur')` no longer returns `nil` (@harold)
+
 # 0.6.5 / 2011-11-04
 
 * Fix bug when parsing ordinal repeaters (#73)

data/README.md

@@ -46,6 +46,10 @@ You can parse strings containing a natural language date using the
 
     Chronic.parse('may 27th', :guess => false)
       #=> Sun May 27 00:00:00 PDT 2007..Mon May 28 00:00:00 PDT 2007
+      
+    Chronic.parse('6/4/2012', :endian_precedence => :little)
+      #=> Fri Apr 06 00:00:00 PDT 2012
+      
 
 See `Chronic.parse` for detailed usage instructions.
 
@@ -86,6 +90,7 @@ Simple
 Complex
 
 * 3 years ago
+* a year ago
 * 5 months before now
 * 7 hours ago
 * 7 days from now

data/chronic.gemspec

@@ -14,4 +14,7 @@ Gem::Specification.new do |s|
   s.extra_rdoc_files = %w[README.md HISTORY.md LICENSE]
   s.files = `git ls-files`.split("\n")
   s.test_files = `git ls-files -- test`.split("\n")
+
+  s.add_development_dependency 'rake'
+  s.add_development_dependency 'minitest'
 end

data/lib/chronic/chronic.rb

@@ -1,5 +1,6 @@
 module Chronic
 
+  # Returns a Hash of default configuration options.
   DEFAULT_OPTIONS = {
     :context => :future,
     :now => nil,
@@ -11,53 +12,43 @@ module Chronic
 
   class << self
 
-    # Parses a string containing a natural language date or time
+    # Parses a string containing a natural language date or time.
     #
     # If the parser can find a date or time, either a Time or Chronic::Span
     # will be returned (depending on the value of `:guess`). If no
-    # date or time can be found, `nil` will be returned
+    # date or time can be found, `nil` will be returned.
     #
-    # @param [String] text The text to parse
+    # text - The String text to parse.
+    # opts - An optional Hash of configuration options:
+    #        :context - If your string represents a birthday, you can set
+    #                   this value to :past and if an ambiguous string is
+    #                   given, it will assume it is in the past.
+    #        :now - Time, all computations will be based off of time
+    #               instead of Time.now.
+    #        :guess - By default the parser will guess a single point in time
+    #                 for the given date or time. If you'd rather have the
+    #                 entire time span returned, set this to false
+    #                 and a Chronic::Span will be returned.
+    #        :ambiguous_time_range - If an Integer is given, ambiguous times
+    #                  (like 5:00) will be assumed to be within the range of
+    #                  that time in the AM to that time in the PM. For
+    #                  example, if you set it to `7`, then the parser will
+    #                  look for the time between 7am and 7pm. In the case of
+    #                  5:00, it would assume that means 5:00pm. If `:none`
+    #                  is given, no assumption will be made, and the first
+    #                  matching instance of that time will be used.
+    #        :endian_precedence - By default, Chronic will parse "03/04/2011"
+    #                 as the fourth day of the third month. Alternatively you
+    #                 can tell Chronic to parse this as the third day of the
+    #                 fourth month by setting this to [:little, :middle].
+    #        :ambiguous_year_future_bias - When parsing two digit years
+    #                 (ie 79) unlike Rubys Time class, Chronic will attempt
+    #                 to assume the full year using this figure. Chronic will
+    #                 look x amount of years into the future and past. If the
+    #                 two digit year is `now + x years` it's assumed to be the
+    #                 future, `now - x years` is assumed to be the past.
     #
-    # @option opts [Symbol] :context (:future)
-    #   * If your string represents a birthday, you can set `:context` to
-    #     `:past` and if an ambiguous string is given, it will assume it is
-    #     in the past. Specify `:future` or omit to set a future context.
-    #
-    # @option opts [Object] :now (Time.now)
-    #   * By setting `:now` to a Time, all computations will be based off of
-    #     that time instead of `Time.now`. If set to nil, Chronic will use
-    #     `Time.now`
-    #
-    # @option opts [Boolean] :guess (true)
-    #   * By default, the parser will guess a single point in time for the
-    #     given date or time. If you'd rather have the entire time span
-    #     returned, set `:guess` to `false` and a {Chronic::Span} will
-    #     be returned
-    #
-    # @option opts [Integer] :ambiguous_time_range (6)
-    #   * If an Integer is given, ambiguous times (like 5:00) will be
-    #     assumed to be within the range of that time in the AM to that time
-    #     in the PM. For example, if you set it to `7`, then the parser
-    #     will look for the time between 7am and 7pm. In the case of 5:00, it
-    #     would assume that means 5:00pm. If `:none` is given, no
-    #     assumption will be made, and the first matching instance of that
-    #     time will be used
-    #
-    # @option opts [Array] :endian_precedence ([:middle, :little])
-    #   * By default, Chronic will parse "03/04/2011" as the fourth day
-    #     of the third month. Alternatively you can tell Chronic to parse
-    #     this as the third day of the fourth month by altering the
-    #     `:endian_precedence` to `[:little, :middle]`
-    #
-    # @option opts [Integer] :ambiguous_year_future_bias (50)
-    #   * When parsing two digit years (ie 79) unlike Rubys Time class,
-    #     Chronic will attempt to assume the full year using this figure.
-    #     Chronic will look x amount of years into the future and past. If
-    #     the two digit year is `now + x years` it's assumed to be the
-    #     future, `now - x years` is assumed to be the past
-    #
-    # @return [Time, Chronic::Span, nil]
+    # Returns a new Time object, or Chronic::Span if :guess option is false.
     def parse(text, opts={})
       options = DEFAULT_OPTIONS.merge opts
 
@@ -87,14 +78,17 @@ module Chronic
       end
     end
 
-    # Clean up the specified text ready for parsing
+    # Clean up the specified text ready for parsing.
     #
     # Clean up the string by stripping unwanted characters, converting
     # idioms to their canonical form, converting number words to numbers
     # (three => 3), and converting ordinal words to numeric
     # ordinals (third => 3rd)
     #
-    # @example
+    # text - The String text to normalize.
+    #
+    # Examples:
+    #
     #   Chronic.pre_normalize('first day in May')
     #     #=> "1st day in may"
     #
@@ -104,17 +98,18 @@ module Chronic
     #   Chronic.pre_normalize('one hundred and thirty six days from now')
     #     #=> "136 days future this second"
     #
-    # @param [String] text The string to normalize
-    # @return [String] A new string ready for Chronic to parse
+    # Returns a new String ready for Chronic to parse.
     def pre_normalize(text)
       text = text.to_s.downcase
-      text.gsub!(/['"\.]/, '')
+      text.gsub!(/\./, ':')
+      text.gsub!(/['"]/, '')
       text.gsub!(/,/, ' ')
+      text.gsub!(/^second /, '2nd ')
       text.gsub!(/\bsecond (of|day|month|hour|minute|second)\b/, '2nd \1')
       text = Numerizer.numerize(text)
       text.gsub!(/ \-(\d{4})\b/, ' tzminus\1')
       text.gsub!(/([\/\-\,\@])/) { ' ' + $1 + ' ' }
-      text.gsub!(/(?:^|\s)0(\d+:\d+\s*pm?\b)/, '\1')
+      text.gsub!(/(?:^|\s)0(\d+:\d+\s*pm?\b)/, ' \1')
       text.gsub!(/\btoday\b/, 'this day')
       text.gsub!(/\btomm?orr?ow\b/, 'next day')
       text.gsub!(/\byesterday\b/, 'last day')
@@ -129,23 +124,26 @@ module Chronic
       text.gsub!(/\b\d+:?\d*[ap]\b/,'\0m')
       text.gsub!(/(\d)([ap]m|oclock)\b/, '\1 \2')
       text.gsub!(/\b(hence|after|from)\b/, 'future')
+      text.gsub!(/^\s?an? /i, '1 ')
+      text.gsub!(/\b(\d{4}):(\d{2}):(\d{2})\b/, '\1 / \2 / \3') # DTOriginal
       text
     end
 
-    # Convert number words to numbers (three => 3, fourth => 4th)
+    # Convert number words to numbers (three => 3, fourth => 4th).
+    #
+    # text - The String to convert.
     #
-    # @see Numerizer.numerize
-    # @param [String] text The string to convert
-    # @return [String] A new string with words converted to numbers
+    # Returns a new String with words converted to numbers.
     def numericize_numbers(text)
       warn "Chronic.numericize_numbers will be deprecated in version 0.7.0. Please use Chronic::Numerizer.numerize instead"
       Numerizer.numerize(text)
     end
 
-    # Guess a specific time within the given span
+    # Guess a specific time within the given span.
+    #
+    # span - The Chronic::Span object to calcuate a guess from.
     #
-    # @param [Span] span
-    # @return [Time]
+    # Returns a new Time object.
     def guess(span)
       if span.width > 1
         span.begin + (span.width / 2)
@@ -154,11 +152,13 @@ module Chronic
       end
     end
 
-    # List of {Handler} definitions. See {parse} for a list of options this
-    # method accepts
+    # List of Handler definitions. See #parse for a list of options this
+    # method accepts.
     #
-    # @see parse
-    # @return [Hash] A Hash of Handler definitions
+    # options - An optional Hash of configuration options:
+    #           :endian_precedence -
+    #
+    # Returns A Hash of Handler definitions.
     def definitions(options={})
       options[:endian_precedence] ||= [:middle, :little]
 
@@ -168,10 +168,11 @@ module Chronic
         ],
 
         :date => [
-          Handler.new([:repeater_day_name, :repeater_month_name, :scalar_day, :repeater_time, :separator_slash_or_dash?, :time_zone, :scalar_year], :handle_rdn_rmn_sd_t_tz_sy),
+          Handler.new([:repeater_day_name, :repeater_month_name, :scalar_day, :repeater_time, :separator_slash_or_dash?, :time_zone, :scalar_year], :handle_generic),
           Handler.new([:repeater_day_name, :repeater_month_name, :scalar_day], :handle_rdn_rmn_sd),
+          Handler.new([:repeater_day_name, :repeater_month_name, :scalar_day, :scalar_year], :handle_rdn_rmn_sd_sy),
           Handler.new([:repeater_day_name, :repeater_month_name, :ordinal_day], :handle_rdn_rmn_od),
-          Handler.new([:scalar_year, :separator_slash_or_dash, :scalar_month, :separator_slash_or_dash, :scalar_day, :repeater_time, :time_zone], :handle_sy_sm_sd_t_tz),
+          Handler.new([:scalar_year, :separator_slash_or_dash, :scalar_month, :separator_slash_or_dash, :scalar_day, :repeater_time, :time_zone], :handle_generic),
           Handler.new([:repeater_month_name, :scalar_day, :scalar_year], :handle_rmn_sd_sy),
           Handler.new([:repeater_month_name, :ordinal_day, :scalar_year], :handle_rmn_od_sy),
           Handler.new([:repeater_month_name, :scalar_day, :scalar_year, :separator_at?, 'time?'], :handle_rmn_sd_sy),
@@ -181,19 +182,23 @@ module Chronic
           Handler.new([:repeater_month_name, :ordinal_day, :separator_at?, 'time?'], :handle_rmn_od),
           Handler.new([:ordinal_day, :repeater_month_name, :scalar_year, :separator_at?, 'time?'], :handle_od_rmn_sy),
           Handler.new([:ordinal_day, :repeater_month_name, :separator_at?, 'time?'], :handle_od_rmn),
+          Handler.new([:ordinal_day, :grabber?, :repeater_month, :separator_at?, 'time?'], :handle_od_rm),
           Handler.new([:scalar_year, :repeater_month_name, :ordinal_day], :handle_sy_rmn_od),
           Handler.new([:repeater_time, :repeater_day_portion?, :separator_on?, :repeater_month_name, :ordinal_day], :handle_rmn_od_on),
           Handler.new([:repeater_month_name, :scalar_year], :handle_rmn_sy),
           Handler.new([:scalar_day, :repeater_month_name, :scalar_year, :separator_at?, 'time?'], :handle_sd_rmn_sy),
           Handler.new([:scalar_day, :repeater_month_name, :separator_at?, 'time?'], :handle_sd_rmn),
           Handler.new([:scalar_year, :separator_slash_or_dash, :scalar_month, :separator_slash_or_dash, :scalar_day, :separator_at?, 'time?'], :handle_sy_sm_sd),
-          Handler.new([:scalar_month, :separator_slash_or_dash, :scalar_year], :handle_sm_sy)
+          Handler.new([:scalar_month, :separator_slash_or_dash, :scalar_year], :handle_sm_sy),
+          Handler.new([:scalar_day, :separator_slash_or_dash, :repeater_month_name, :separator_slash_or_dash, :scalar_year, :repeater_time?], :handle_sm_rmn_sy),
+          Handler.new([:scalar_year, :separator_slash_or_dash, :scalar_month, :separator_slash_or_dash, :time_zone], :handle_generic)
+
         ],
 
         # tonight at 7pm
         :anchor => [
-          Handler.new([:grabber?, :repeater, :separator_at?, :repeater?, :repeater?], :handle_r),
-          Handler.new([:grabber?, :repeater, :repeater, :separator_at?, :repeater?, :repeater?], :handle_r),
+          Handler.new([:separator_on?, :grabber?, :repeater, :separator_at?, :repeater?, :repeater?], :handle_r),
+          Handler.new([:grabber?, :repeater, :repeater, :separator?, :repeater?, :repeater?], :handle_r),
           Handler.new([:repeater, :grabber, :repeater], :handle_r_g_r)
         ],
 
@@ -201,7 +206,7 @@ module Chronic
         :arrow => [
           Handler.new([:scalar, :repeater, :pointer], :handle_s_r_p),
           Handler.new([:pointer, :scalar, :repeater], :handle_p_s_r),
-          Handler.new([:scalar, :repeater, :pointer, 'anchor'], :handle_s_r_p_a)
+          Handler.new([:scalar, :repeater, :pointer, :separator_at?, 'anchor'], :handle_s_r_p_a)
         ],
 
         # 3rd week in march
@@ -213,6 +218,8 @@ module Chronic
 
       endians = [
         Handler.new([:scalar_month, :separator_slash_or_dash, :scalar_day, :separator_slash_or_dash, :scalar_year, :separator_at?, 'time?'], :handle_sm_sd_sy),
+        Handler.new([:scalar_month, :separator_slash_or_dash, :scalar_day, :separator_at?, 'time?'], :handle_sm_sd),
+        Handler.new([:scalar_day, :separator_slash_or_dash, :scalar_month, :separator_at?, 'time?'], :handle_sd_sm),
         Handler.new([:scalar_day, :separator_slash_or_dash, :scalar_month, :separator_slash_or_dash, :scalar_year, :separator_at?, 'time?'], :handle_sd_sm_sy)
       ]
 
@@ -228,9 +235,17 @@ module Chronic
       @definitions
     end
 
-    # Construct a time Object
+    # Construct a new time object determining possible month overflows
+    # and leap years.
+    #
+    # year   - Integer year.
+    # month  - Integer month.
+    # day    - Integer day.
+    # hour   - Integer hour.
+    # minute - Integer minute.
+    # second - Integer second.
     #
-    # @return [Time]
+    # Returns a new Time object constructed from these params.
     def construct(year, month = 1, day = 1, hour = 0, minute = 0, second = 0)
       if second >= 60
         minute += second / 60

data/lib/chronic/grabber.rb

@@ -1,20 +1,22 @@
 module Chronic
   class Grabber < Tag
 
-    # Scan an Array of {Token}s and apply any necessary Grabber tags to
-    # each token
+    # Scan an Array of Tokens and apply any necessary Grabber tags to
+    # each token.
     #
-    # @param [Array<Token>] tokens Array of tokens to scan
-    # @param [Hash] options Options specified in {Chronic.parse}
-    # @return [Array] list of tokens
+    # tokens  - An Array of Token objects to scan.
+    # options - The Hash of options specified in Chronic::parse.
+    #
+    # Returns an Array of Token objects.
     def self.scan(tokens, options)
       tokens.each do |token|
         if t = scan_for_all(token) then token.tag(t); next end
       end
     end
 
-    # @param [Token] token
-    # @return [Grabber, nil]
+    # token - The Token object to scan.
+    #
+    # Returns a new Grabber object.
     def self.scan_for_all(token)
       scan_for token, self,
       {

data/lib/chronic/handler.rb

@@ -1,25 +1,22 @@
 module Chronic
   class Handler
 
-    # @return [Array] A list of patterns
     attr_reader :pattern
 
-    # @return [Symbol] The method which handles this list of patterns.
-    #   This method should exist inside the {Handlers} module
     attr_reader :handler_method
 
-    # @param [Array]  pattern A list of patterns to match tokens against
-    # @param [Symbol] handler_method The method to be invoked when patterns
-    #   are matched. This method should exist inside the {Handlers} module
+    # pattern        - An Array of patterns to match tokens against.
+    # handler_method - A Symbole representing the method to be invoked
+    #   when patterns are matched.
     def initialize(pattern, handler_method)
       @pattern = pattern
       @handler_method = handler_method
     end
 
-    # @param [Array] tokens
-    # @param [Hash]  definitions
-    # @return [Boolean]
-    # @see Chronic.tokens_to_span
+    # tokens - An Array of tokens to process.
+    # definitions - A Hash of definitions to check against.
+    #
+    # Returns true if a match is found.
     def match(tokens, definitions)
       token_index = 0
 
@@ -70,8 +67,9 @@ module Chronic
       Handlers.send(@handler_method, tokens, options)
     end
 
-    # @param [Handler]  The handler to compare
-    # @return [Boolean] True if these handlers match
+    # other - The other Handler object to compare.
+    #
+    # Returns true if these Handlers match.
     def ==(other)
       @pattern == other.pattern
     end

data/lib/chronic/handlers.rb

@@ -49,6 +49,13 @@ module Chronic
       handle_m_d(month, day, tokens[2..tokens.size], options)
     end
 
+    # Handle ordinal this month
+    def handle_od_rm(tokens, options)
+      day = tokens[0].get_tag(OrdinalDay).type
+      month = tokens[2].get_tag(RepeaterMonth)
+      handle_m_d(month, day, tokens[3..tokens.size], options)
+    end
+
     # Handle ordinal-day/repeater-month-name
     def handle_od_rmn(tokens, options)
       month = tokens[1].get_tag(RepeaterMonthName)
@@ -124,13 +131,7 @@ module Chronic
     end
 
     # Handle generic timestamp (ruby 1.8)
-    def handle_rdn_rmn_sd_t_tz_sy(tokens, options)
-      t = Chronic.time_class.parse(options[:text])
-      Span.new(t, t + 1)
-    end
-
-    # Handle generic timestamp (ruby 1.9)
-    def handle_sy_sm_sd_t_tz(tokens, options)
+    def handle_generic(tokens, options)
       t = Chronic.time_class.parse(options[:text])
       Span.new(t, t + 1)
     end
@@ -224,6 +225,30 @@ module Chronic
       handle_sm_sd_sy(new_tokens + time_tokens, options)
     end
 
+    # Handle scalar-month/scalar-day
+    def handle_sm_sd(tokens, options)
+      month = tokens[0].get_tag(ScalarMonth).type
+      day = tokens[1].get_tag(ScalarDay).type
+      year = Chronic.now.year
+      time_tokens = tokens.last(tokens.size - 2)
+
+      return if month_overflow?(year, month, day)
+
+      begin
+        day_start = Chronic.time_class.local(year, month, day)
+        day_or_time(day_start, time_tokens, options)
+      rescue ArgumentError
+        nil
+      end
+    end
+
+    # Handle scalar-day/scalar-month
+    def handle_sd_sm(tokens, options)
+      new_tokens = [tokens[1], tokens[0]]
+      time_tokens = tokens.last(tokens.size - 2)
+      handle_sm_sd(new_tokens + time_tokens, options)
+    end
+
     # Handle scalar-month/scalar-year
     def handle_sm_sy(tokens, options)
       month = tokens[0].get_tag(ScalarMonth).type
@@ -255,7 +280,7 @@ module Chronic
 
       begin
         start_time = Chronic.time_class.local(year, month.index, day)
-        end_time = Chronic.time_class.local(year, month.index, day + 1)
+        end_time = time_with_rollover(year, month.index, day + 1)
         Span.new(start_time, end_time)
       rescue ArgumentError
         nil
@@ -272,13 +297,46 @@ module Chronic
 
       begin
         start_time = Chronic.time_class.local(year, month.index, day)
-        end_time = Chronic.time_class.local(year, month.index, day + 1)
+        end_time = time_with_rollover(year, month.index, day + 1)
+        Span.new(start_time, end_time)
+      rescue ArgumentError
+        nil
+      end
+    end
+
+    # Handle RepeaterDayName RepeaterMonthName ScalarDay ScalarYear
+    def handle_rdn_rmn_sd_sy(tokens, options)
+      month = tokens[1].get_tag(RepeaterMonthName)
+      day = tokens[2].get_tag(ScalarDay).type
+      year = tokens[3].get_tag(ScalarYear).type
+
+      return if month_overflow?(year, month.index, day)
+
+      begin
+        start_time = Chronic.time_class.local(year, month.index, day)
+        end_time = time_with_rollover(year, month.index, day + 1)
         Span.new(start_time, end_time)
       rescue ArgumentError
         nil
       end
     end
 
+    def handle_sm_rmn_sy(tokens, options)
+      day = tokens[0].get_tag(ScalarDay).type
+      month = tokens[1].get_tag(RepeaterMonthName).index
+      year = tokens[2].get_tag(ScalarYear).type
+      if tokens.size > 3
+        time = get_anchor([tokens.last], options).begin
+        h, m, s = time.hour, time.min, time.sec
+        time = Chronic.time_class.local(year, month, day, h, m, s)
+        end_time = Chronic.time_class.local(year, month, day + 1, h, m, s)
+      else
+        time = Chronic.time_class.local(year, month, day)
+        end_time = Chronic.time_class.local(year, month, day + 1)
+      end
+      Span.new(time, end_time)
+    end
+
     # anchors
 
     # Handle repeaters
@@ -301,7 +359,7 @@ module Chronic
       repeater = tokens[1].get_tag(Repeater)
       pointer = tokens[2].get_tag(Pointer).type
 
-      repeater.offset(span, distance, pointer)
+      repeater.offset(span, distance, pointer) if repeater.respond_to?(:offset)
     end
 
     # Handle scalar/repeater/pointer
@@ -373,7 +431,6 @@ module Chronic
     def get_anchor(tokens, options)
       grabber = Grabber.new(:this)
       pointer = :future
-
       repeaters = get_repeaters(tokens)
       repeaters.size.times { tokens.pop }
 
@@ -417,6 +474,8 @@ module Chronic
       else
         day > RepeaterMonth::MONTH_DAYS[month - 1]
       end
+    rescue ArgumentError
+      false
     end
 
     # Recursively finds repeaters within other repeaters.
@@ -435,6 +494,20 @@ module Chronic
       end
     end
 
+    def time_with_rollover(year, month, day)
+      date_parts =
+        if month_overflow?(year, month, day)
+          if month == 12
+            [year + 1, 1, 1]
+          else
+            [year, month + 1, 1]
+          end
+        else
+          [year, month, day]
+        end
+      Chronic.time_class.local(*date_parts)
+    end
+
     def dealias_and_disambiguate_times(tokens, options)
       # handle aliases of am/pm
       # 5:00 in the morning -> 5:00 am

data/lib/chronic/ordinal.rb

@@ -1,12 +1,13 @@
 module Chronic
   class Ordinal < Tag
 
-    # Scan an Array of {Token}s and apply any necessary Ordinal tags to
-    # each token
+    # Scan an Array of Token objects and apply any necessary Ordinal
+    # tags to each token.
     #
-    # @param [Array<Token>] tokens Array of tokens to scan
-    # @param [Hash] options Options specified in {Chronic.parse}
-    # @return [Array] list of tokens
+    # tokens - An Array of tokens to scan.
+    # options - The Hash of options specified in Chronic::parse.
+    #
+    # Returns an Array of tokens.
     def self.scan(tokens, options)
       tokens.each do |token|
         if t = scan_for_ordinals(token) then token.tag(t) end
@@ -14,14 +15,16 @@ module Chronic
       end
     end
 
-    # @param [Token] token
-    # @return [Ordinal, nil]
+    # token - The Token object we want to scan.
+    #
+    # Returns a new Ordinal object.
     def self.scan_for_ordinals(token)
       Ordinal.new($1.to_i) if token.word =~ /^(\d*)(st|nd|rd|th)$/
     end
 
-    # @param [Token] token
-    # @return [OrdinalDay, nil]
+    # token - The Token object we want to scan.
+    #
+    # Returns a new Ordinal object.
     def self.scan_for_days(token)
       if token.word =~ /^(\d*)(st|nd|rd|th)$/
         unless $1.to_i > 31 || $1.to_i < 1

data/lib/chronic/pointer.rb

@@ -1,20 +1,22 @@
 module Chronic
   class Pointer < Tag
 
-    # Scan an Array of {Token}s and apply any necessary Pointer tags to
-    # each token
+    # Scan an Array of Token objects and apply any necessary Pointer
+    # tags to each token.
     #
-    # @param [Array<Token>] tokens Array of tokens to scan
-    # @param [Hash] options Options specified in {Chronic.parse}
-    # @return [Array] list of tokens
+    # tokens - An Array of tokens to scan.
+    # options - The Hash of options specified in Chronic::parse.
+    #
+    # Returns an Array of tokens.
     def self.scan(tokens, options)
       tokens.each do |token|
         if t = scan_for_all(token) then token.tag(t) end
       end
     end
 
-    # @param [Token] token
-    # @return [Pointer, nil]
+    # token - The Token object we want to scan.
+    #
+    # Returns a new Pointer object.
     def self.scan_for_all(token)
       scan_for token, self,
       {