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.

git-svn-id: svn+ssh://ci.ruby-lang.org/ruby/trunk@66082 b2dd03c8-39d4-4d8f-98ff-823fe69b080e

1 files changed, 101 insertions, 73 deletions

diff --git a/lib/time.rb b/lib/time.rb
index a2ada7728b..49ef68a5e2 100644
--- a/lib/time.rb
+++ b/lib/time.rb
@@ -2,6 +2,8 @@
 
 require 'date'
 
+# :stopdoc:
+
 # = time.rb
 #
 # When 'time' is required, Time is extended with additional methods for parsing
@@ -18,73 +20,8 @@ require 'date'
 #   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
     #
     # 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
     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
     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
     # %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
     #
     # 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
     #
     # 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
     #
     # 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
   #
   # 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
   #
   # 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
   # +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)