ruby-changes:53863
From: nobu <ko1@a...>
Date: Thu, 29 Nov 2018 10:10:01 +0900 (JST)
Subject: [ruby-changes:53863] nobu:r66082 (trunk): time.rb: Move documents and stop others
nobu 2018-11-29 10:09:47 +0900 (Thu, 29 Nov 2018) New Revision: 66082 https://svn.ruby-lang.org/cgi-bin/viewvc.cgi?view=revision&revision=66082 Log: time.rb: Move documents and stop others * lib/time.rb: Move method documents to each methods. And stop documentation of the abstract and others, which were confusingly placed at the top of generated documents prior to the abstract in time.c. Modified files: trunk/lib/time.rb Index: lib/time.rb =================================================================== --- lib/time.rb (revision 66081) +++ lib/time.rb (revision 66082) @@ -2,6 +2,8 @@ https://github.com/ruby/ruby/blob/trunk/lib/time.rb#L2 require 'date' +# :stopdoc: + # = time.rb # # When 'time' is required, Time is extended with additional methods for parsing @@ -18,73 +20,8 @@ require 'date' https://github.com/ruby/ruby/blob/trunk/lib/time.rb#L20 # 8601}[http://www.iso.org/iso/date_and_time_format]) # * various formats handled by Date._parse # * custom formats handled by Date._strptime -# -# == Examples -# -# All examples assume you have loaded Time with: -# -# require 'time' -# -# All of these examples were done using the EST timezone which is GMT-5. -# -# === Converting to a String -# -# 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" -# -# === Time.parse -# -# #parse takes a string representation of a Time and attempts to parse it -# using a heuristic. -# -# Time.parse("2010-10-31") #=> 2010-10-31 00:00:00 -0500 -# -# Any missing pieces of the date are inferred based on the current date. -# -# # assuming the current date is "2011-10-31" -# Time.parse("12:00") #=> 2011-10-31 12:00:00 -0500 -# -# We can change the date used to infer our missing elements by passing a second -# object that responds to #mon, #day and #year, such as Date, Time or DateTime. -# We can also use our own object. -# -# class MyDate -# attr_reader :mon, :day, :year -# -# def initialize(mon, day, year) -# @mon, @day, @year = mon, day, year -# end -# end -# -# d = Date.parse("2010-10-28") -# t = Time.parse("2010-10-29") -# dt = DateTime.parse("2010-10-30") -# md = MyDate.new(10,31,2010) -# -# Time.parse("12:00", d) #=> 2010-10-28 12:00:00 -0500 -# Time.parse("12:00", t) #=> 2010-10-29 12:00:00 -0500 -# Time.parse("12:00", dt) #=> 2010-10-30 12:00:00 -0500 -# Time.parse("12:00", md) #=> 2010-10-31 12:00:00 -0500 -# -# #parse also accepts an optional block. You can use this block to specify how -# to handle the year component of the date. This is specifically designed for -# handling two digit years. For example, if you wanted to treat all two digit -# years prior to 70 as the year 2000+ you could write this: -# -# Time.parse("01-10-31") {|year| year + (year < 70 ? 2000 : 1900)} -# #=> 2001-10-31 00:00:00 -0500 -# Time.parse("70-10-31") {|year| year + (year < 70 ? 2000 : 1900)} -# #=> 1970-10-31 00:00:00 -0500 -# -# === Time.strptime -# -# #strptime works similar to +parse+ except that instead of using a heuristic -# to detect the format of the input string, you provide a second argument that -# describes the format of the string. For example: -# -# Time.strptime("2000-10-31", "%Y-%m-%d") #=> 2000-10-31 00:00:00 -0500 + +# :startdoc: class Time class << Time @@ -131,6 +68,13 @@ class Time https://github.com/ruby/ruby/blob/trunk/lib/time.rb#L68 # # If +zone_offset+ is unable to determine the offset, nil will be # returned. + # + # require 'time' + # + # Time.zone_offset("EST") #=> -18000 + # + # You must require 'time' to use this method. + # def zone_offset(zone, year=self.now.year) off = nil zone = zone.upcase @@ -316,17 +260,62 @@ class Time https://github.com/ruby/ruby/blob/trunk/lib/time.rb#L260 private :make_time # - # Parses +date+ using Date._parse and converts it to a Time object. + # Takes a string representation of a Time and attempts to parse it + # using a heuristic. # - # If a block is given, the year described in +date+ is converted by the - # block. For example: + # require 'time' + # + # Time.parse("2010-10-31") #=> 2010-10-31 00:00:00 -0500 # - # Time.parse(...) {|y| 0 <= y && y < 100 ? (y >= 69 ? y + 1900 : y + 2000) : y} + # Any missing pieces of the date are inferred based on the current date. + # + # require 'time' + # + # # assuming the current date is "2011-10-31" + # Time.parse("12:00") #=> 2011-10-31 12:00:00 -0500 + # + # We can change the date used to infer our missing elements by passing a second + # object that responds to #mon, #day and #year, such as Date, Time or DateTime. + # We can also use our own object. + # + # require 'time' + # + # class MyDate + # attr_reader :mon, :day, :year + # + # def initialize(mon, day, year) + # @mon, @day, @year = mon, day, year + # end + # end + # + # d = Date.parse("2010-10-28") + # t = Time.parse("2010-10-29") + # dt = DateTime.parse("2010-10-30") + # md = MyDate.new(10,31,2010) + # + # Time.parse("12:00", d) #=> 2010-10-28 12:00:00 -0500 + # Time.parse("12:00", t) #=> 2010-10-29 12:00:00 -0500 + # Time.parse("12:00", dt) #=> 2010-10-30 12:00:00 -0500 + # Time.parse("12:00", md) #=> 2010-10-31 12:00:00 -0500 + # + # If a block is given, the year described in +date+ is converted + # by the block. This is specifically designed for handling two + # digit years. For example, if you wanted to treat all two digit + # years prior to 70 as the year 2000+ you could write this: + # + # require 'time' + # + # Time.parse("01-10-31") {|year| year + (year < 70 ? 2000 : 1900)} + # #=> 2001-10-31 00:00:00 -0500 + # Time.parse("70-10-31") {|year| year + (year < 70 ? 2000 : 1900)} + # #=> 1970-10-31 00:00:00 -0500 # # If the upper components of the given time are broken or missing, they are # supplied with those of +now+. For the lower components, the minimum # values (1 or 0) are assumed if broken or missing. For example: # + # require 'time' + # # # Suppose it is "Thu Nov 29 14:33:20 2001" now and # # your time zone is EST which is GMT-5. # now = Time.parse("Thu Nov 29 14:33:20 2001") @@ -378,7 +367,9 @@ class Time https://github.com/ruby/ruby/blob/trunk/lib/time.rb#L367 end # - # Parses +date+ using Date._strptime and converts it to a Time object. + # Works similar to +parse+ except that instead of using a + # heuristic to detect the format of the input string, you provide + # a second argument that describes the format of the string. # # If a block is given, the year described in +date+ is converted by the # block. For example: @@ -436,7 +427,13 @@ class Time https://github.com/ruby/ruby/blob/trunk/lib/time.rb#L427 # %Z :: Time zone name # %% :: Literal "%" character # %+ :: date(1) (%a %b %e %H:%M:%S %Z %Y) - + # + # require 'time' + # + # Time.strptime("2000-10-31", "%Y-%m-%d") #=> 2000-10-31 00:00:00 -0500 + # + # You must require 'time' to use this method. + # def strptime(date, format, now=self.now) d = Date._strptime(date, format) raise ArgumentError, "invalid strptime format - `#{format}'" unless d @@ -474,6 +471,11 @@ class Time https://github.com/ruby/ruby/blob/trunk/lib/time.rb#L471 # # See #rfc2822 for more information on this format. # + # require 'time' + # + # Time.rfc2822("Wed, 05 Oct 2011 22:26:12 -0400") + # #=> 2010-10-05 22:26:12 -0400 + # # You must require 'time' to use this method. # def rfc2822(date) @@ -527,6 +529,11 @@ class Time https://github.com/ruby/ruby/blob/trunk/lib/time.rb#L529 # # See #httpdate for more information on this format. # + # require 'time' + # + # Time.httpdate("Thu, 06 Oct 2011 02:26:12 GMT") + # #=> 2011-10-06 02:26:12 UTC + # # You must require 'time' to use this method. # def httpdate(date) @@ -576,6 +583,12 @@ class Time https://github.com/ruby/ruby/blob/trunk/lib/time.rb#L583 # # See #xmlschema for more information on this format. # + # require 'time' + # + # t = Time.now + # Time.xmlschema("2011-10-05T22:26:12-04:00") + # #=> 2011-10-05 22:26:12-04:00 + # # You must require 'time' to use this method. # def xmlschema(date) @@ -623,6 +636,11 @@ class Time https://github.com/ruby/ruby/blob/trunk/lib/time.rb#L636 # # If +self+ is a UTC time, -0000 is used as zone. # + # require 'time' + # + # t = Time.now + # t.rfc2822 # => "Wed, 05 Oct 2011 22:26:12 -0400" + # # You must require 'time' to use this method. # def rfc2822 @@ -658,6 +676,11 @@ class Time https://github.com/ruby/ruby/blob/trunk/lib/time.rb#L676 # # Note that the result is always UTC (GMT). # + # require 'time' + # + # t = Time.now + # t.httpdate # => "Thu, 06 Oct 2011 02:26:12 GMT" + # # You must require 'time' to use this method. # def httpdate @@ -682,6 +705,11 @@ class Time https://github.com/ruby/ruby/blob/trunk/lib/time.rb#L705 # +fractional_digits+ specifies a number of digits to use for fractional # seconds. Its default value is 0. # + # require 'time' + # + # t = Time.now + # t.iso8601 # => "2011-10-05T22:26:12-04:00" + # # You must require 'time' to use this method. # def xmlschema(fraction_digits=0) -- ML: ruby-changes@q... Info: http://www.atdot.net/~ko1/quickml/