chronic 0.6.2 → 0.7.0

data/.gitignore

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

data/HISTORY.md

@@ -1,3 +1,39 @@
+# HEAD
+
+* 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)
+* Added handler support for day_name month_name (@imme5150)
+* Fix bug when parsing strings prefixed with PM
+
+# 0.6.4 / 2011-08-08
+
+* Fixed bug where 'noon' was parsed as 00:00 rather than 12:00
+  with :ambiguous_time_range => :none (Vladimir Chernis)
+* Add support for handling '2009 May 22nd'
+* Add the ability to handle scalar-day/repeater-month-name as well as ordinals
+
+# 0.6.3 / 2011-08-01
+
+* Ensure 'thu' is parsed as Thursday for 1.8.7 generic timestamp
+
 # 0.6.2 / 2011-07-28
 
 * Ensure specific endian handlers are prioritised over normal date handlers

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
@@ -162,14 +167,13 @@ If you'd like to hack on Chronic, start by forking the repo on GitHub:
 
 https://github.com/mojombo/chronic
 
-To get all of the dependencies, install the gem first. The best way to get
-your changes merged back into core is as follows:
+The best way to get your changes merged back into core is as follows:
 
 1. Clone down your fork
 1. Create a thoughtfully named topic branch to contain your change
 1. Hack away
 1. Add tests and make sure everything still passes by running `rake`
-1. Ensure your tests pass in multiple timezones
+1. Ensure your tests pass in multiple timezones. ie `TZ=utc rake` `TZ=BST rake`
 1. If you are adding new functionality, document it in the README
 1. Do not change the version number, we will do that on our end
 1. If necessary, rebase your commits into logical chunks, without errors

data/Rakefile

@@ -5,11 +5,9 @@ def version
   contents[/VERSION = "([^"]+)"/, 1]
 end
 
-require 'rake/testtask'
-Rake::TestTask.new(:test) do |test|
-  test.libs << 'lib' << 'test'
-  test.pattern = 'test/**/test_*.rb'
-  test.verbose = true
+task :test do
+  $:.unshift './test'
+  Dir.glob('test/test_*.rb').each { |t| require File.basename(t) }
 end
 
 desc "Generate RCov test coverage and open in your browser"

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,21 +98,22 @@ 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!(/\b0(\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')
-      text.gsub!(/\bnoon\b/, '12:00')
+      text.gsub!(/\bnoon\b/, '12:00pm')
       text.gsub!(/\bmidnight\b/, '24:00')
       text.gsub!(/\bnow\b/, 'this second')
       text.gsub!(/\b(?:ago|before(?: now)?)\b/, 'past')
@@ -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.
     #
-    # @param [Span] span
-    # @return [Time]
+    # span - The Chronic::Span object to calcuate a guess from.
+    #
+    # 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.
+    #
+    # options - An optional Hash of configuration options:
+    #           :endian_precedence -
     #
-    # @see parse
-    # @return [Hash] A Hash of Handler definitions
+    # Returns A Hash of Handler definitions.
     def definitions(options={})
       options[:endian_precedence] ||= [:middle, :little]
 
@@ -169,6 +169,9 @@ 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], :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([:repeater_month_name, :scalar_day, :scalar_year], :handle_rmn_sd_sy),
           Handler.new([:repeater_month_name, :ordinal_day, :scalar_year], :handle_rmn_od_sy),
@@ -179,11 +182,15 @@ 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([: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_day], :handle_sm_sd),
+          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], :handle_sm_rmn_sy)
         ],
 
         # tonight at 7pm
@@ -224,9 +231,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

@@ -59,6 +59,32 @@ module Chronic
       handle_m_d(month, day, tokens[2..tokens.size], options)
     end
 
+    def handle_sy_rmn_od(tokens, options)
+      year = tokens[0].get_tag(ScalarYear).type
+      month = tokens[1].get_tag(RepeaterMonthName).index
+      day = tokens[2].get_tag(OrdinalDay).type
+      time_tokens = tokens.last(tokens.size - 3)
+
+      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/repeater-month-name
+    def handle_sd_rmn(tokens, options)
+      month = tokens[1].get_tag(RepeaterMonthName)
+      day = tokens[0].get_tag(ScalarDay).type
+
+      return if month_overflow?(Chronic.now.year, month.index, day)
+
+      handle_m_d(month, day, tokens[2..tokens.size], options)
+    end
+
     # Handle repeater-month-name/ordinal-day with separator-on
     def handle_rmn_od_on(tokens, options)
       if tokens.size > 3
@@ -198,6 +224,27 @@ module Chronic
       handle_sm_sd_sy(new_tokens + time_tokens, options)
     end
 
+    # Handle scalar-day/scalar-month AND 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
+
+      if Array(options[:endian_precedence]).first == :little
+        day, month = month, day
+      end
+
+      return if month_overflow?(year, month, day)
+
+      begin
+        start_time = Chronic.time_class.local(year, month, day)
+        end_time = Chronic.time_class.local(year, month, day + 1)
+        Span.new(start_time, end_time)
+      rescue ArgumentError
+        nil
+      end
+    end
+
     # Handle scalar-month/scalar-year
     def handle_sm_sy(tokens, options)
       month = tokens[0].get_tag(ScalarMonth).type
@@ -219,6 +266,66 @@ module Chronic
       end
     end
 
+    # Handle RepeaterDayName RepeaterMonthName OrdinalDay
+    def handle_rdn_rmn_od(tokens, options)
+      month = tokens[1].get_tag(RepeaterMonthName)
+      day = tokens[2].get_tag(OrdinalDay).type
+      year = Chronic.now.year
+
+      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
+
+    # Handle RepeaterDayName RepeaterMonthName ScalarDay
+    def handle_rdn_rmn_sd(tokens, options)
+      month = tokens[1].get_tag(RepeaterMonthName)
+      day = tokens[2].get_tag(ScalarDay).type
+      year = Chronic.now.year
+
+      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
+
+    # 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
+      time = Chronic.time_class.local(year, month, day)
+      end_time = Chronic.time_class.local(year, month, day + 1)
+      Span.new(time, end_time)
+    end
+
     # anchors
 
     # Handle repeaters
@@ -241,7 +348,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
@@ -276,7 +383,7 @@ module Chronic
       ordinal.times do
         span = repeater.next(:future)
 
-        if span.begin > outer_span.end
+        if span.begin >= outer_span.end
           span = nil
           break
         end
@@ -339,7 +446,11 @@ module Chronic
         raise ChronicPain, "Invalid grabber"
       end
 
-      puts "--#{outer_span}" if Chronic.debug
+      if Chronic.debug
+        puts "Handler-class: #{head.class}"
+        puts "--#{outer_span}"
+      end
+
       find_within(repeaters, outer_span, pointer)
     end
 
@@ -353,6 +464,8 @@ module Chronic
       else
         day > RepeaterMonth::MONTH_DAYS[month - 1]
       end
+    rescue ArgumentError
+      false
     end
 
     # Recursively finds repeaters within other repeaters.
@@ -371,6 +484,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,
       {