From 4fb9d3c66fdba6f9ba4b9c447a1159ab70f21ec6 Mon Sep 17 00:00:00 2001 From: Jake Goulding Date: Wed, 5 Oct 2011 23:08:42 -0400 Subject: [PATCH 4/4] General cleanup of time.rb documentation Added some missing articles, removed references to requiring the library from each individual method, and added some examples of converting strings to Time objects at the top. --- lib/time.rb | 75 +++++++++++++++++++++------------------------------------- 1 files changed, 27 insertions(+), 48 deletions(-) diff --git a/lib/time.rb b/lib/time.rb index 37a90d0..a382f85 100644 --- a/lib/time.rb +++ b/lib/time.rb @@ -12,10 +12,18 @@ require 'date' # # require 'time' # +# # Convert a time object to useful time strings # t = Time.now # t.iso8601 # => "2011-10-05T22:26:12-04:00" # t.rfc2822 # => "Wed, 05 Oct 2011 22:26:12 -0400" # t.httpdate # => "Thu, 06 Oct 2011 02:26:12 GMT" +# +# # Parse a time string to a time object +# Time.parse('2011-01-01 01:23:45 -0400') # => 2011-01-01 00:23:45 -0500 +# Time.iso8601("2011-10-05T22:26:12-04:00") # => 2011-10-06 02:26:12 UTC +# Time.rfc2822("Wed, 05 Oct 2011 22:26:12 -0400") # => 2011-10-05 22:26:12 -0400 +# Time.httpdate("Thu, 06 Oct 2011 02:26:12 GMT") # => 2011-10-05 22:26:12 -0400 +# class Time class << Time @@ -220,7 +228,7 @@ class Time # Time.parse("Aug 2000", now) #=> 2000-08-01 00:00:00 +0900 # # Since there are numerous conflicts among locally defined time zone - # abbreviations all over the world, this method is not made to + # abbreviations all over the world, this method is not intended to # understand all of them. For example, the abbreviation "CST" is # used variously as: # @@ -231,7 +239,7 @@ class Time # +10:30 in Australia/Adelaide, # etc. # - # Based on the fact, this method only understands the time zone + # Based on this fact, this method only understands the time zone # abbreviations described in RFC 822 and the system time zone, in the # order named. (i.e. a definition in RFC 822 overrides the system # time zone definition.) The system time zone is taken from @@ -241,19 +249,15 @@ class Time # it is ignored and the given time is regarded as a local time. # # ArgumentError is raised if Date._parse cannot extract information from - # +date+ or Time class cannot represent specified date. + # +date+ or if the Time class cannot represent the specified date. # - # This method can be used as fail-safe for other parsing methods as: + # This method can be used as a fail-safe for other parsing methods as: # # Time.rfc2822(date) rescue Time.parse(date) # Time.httpdate(date) rescue Time.parse(date) # Time.xmlschema(date) rescue Time.parse(date) # - # A failure for Time.parse should be checked, though. - # - # time library should be required to use this method as follows. - # - # require 'time' + # A failure of Time.parse should be checked, though. # def parse(date, now=self.now) comp = !block_given? @@ -292,14 +296,10 @@ class Time # updated by RFC 1123. # # ArgumentError is raised if +date+ is not compliant with RFC 2822 - # or Time class cannot represent specified date. + # or if the Time class cannot represent the specified date. # # See #rfc2822 for more information on this format. # - # time library should be required to use this method as follows. - # - # require 'time' - # def rfc2822(date) if /\A\s* (?:(?:Mon|Tue|Wed|Thu|Fri|Sat|Sun)\s*,\s*)? @@ -341,18 +341,14 @@ class Time alias rfc822 rfc2822 # - # Parses +date+ as HTTP-date defined by RFC 2616 and converts it to a Time + # Parses +date+ as an HTTP-date defined by RFC 2616 and converts it to a Time # object. # - # ArgumentError is raised if +date+ is not compliant with RFC 2616 or Time - # class cannot represent specified date. + # ArgumentError is raised if +date+ is not compliant with RFC 2616 + # or if the Time class cannot represent the specified date. # # See #httpdate for more information on this format. # - # time library should be required to use this method as follows. - # - # require 'time' - # def httpdate(date) if /\A\s* (?:Mon|Tue|Wed|Thu|Fri|Sat|Sun),\x20 @@ -391,19 +387,15 @@ class Time end # - # Parses +date+ as dateTime defined by XML Schema and converts it to a Time - # object. The format is restricted version of the format defined by ISO - # 8601. + # Parses +date+ as a dateTime defined by XML Schema and converts + # it to a Time object. The format is a restricted version of the + # format defined by ISO 8601. # - # ArgumentError is raised if +date+ is not compliant with the format or Time - # class cannot represent specified date. + # ArgumentError is raised if +date+ is not compliant with the + # format or if the Time class cannot represent the specified date. # # See #xmlschema for more information on this format. # - # time library should be required to use this method as follows. - # - # require 'time' - # def xmlschema(date) if /\A\s* (-?\d+)-(\d\d)-(\d\d) @@ -446,10 +438,6 @@ class Time # # If +self+ is a UTC time, -0000 is used as zone. # - # time library should be required to use this method as follows. - # - # require 'time' - # def rfc2822 sprintf('%s, %02d %s %0*d %02d:%02d:%02d ', RFC2822_DAY_NAME[wday], @@ -474,17 +462,13 @@ class Time ] # - # Returns a string which represents the time as rfc1123-date of HTTP-date - # defined by RFC 2616: + # Returns a string which represents the time as the +rfc1123-date+ of + # HTTP-date as defined by RFC 2616: # # day-of-week, DD month-name CCYY hh:mm:ss GMT # # Note that the result is always UTC (GMT). # - # time library should be required to use this method as follows. - # - # require 'time' - # def httpdate t = dup.utc sprintf('%s, %02d %s %0*d %02d:%02d:%02d GMT', @@ -494,7 +478,7 @@ class Time end # - # Returns a string which represents the time as dateTime defined by XML + # Returns a string which represents the time as a dateTime defined by XML # Schema: # # CCYY-MM-DDThh:mm:ssTZD @@ -504,12 +488,8 @@ class Time # # If self is a UTC time, Z is used as TZD. [+-]hh:mm is used otherwise. # - # +fractional_seconds+ specifies a number of digits of fractional seconds. - # Its default value is 0. - # - # time library should be required to use this method as follows. - # - # require 'time' + # +fractional_seconds+ specifies a number of digits to use for + # fractional seconds. # def xmlschema(fraction_digits=0) sprintf('%0*d-%02d-%02dT%02d:%02d:%02d', @@ -529,4 +509,3 @@ class Time end alias iso8601 xmlschema end - -- 1.7.7