* time.c (Init_Time): Improve Time documentation. Patch by Shane

  Emmons.  [Ruby 1.9 - Bug #5404]
* lib/time.rb:  Improve time.rb documentation including Time.strptime.
  Patch by Shane Emmons.  [Ruby 1.9 - Bug #5402]


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

1 files changed, 78 insertions, 14 deletions

diff --git a/time.c b/time.c
index a18548ea36..00b80506f2 100644
--- a/time.c
+++ b/time.c
@@ -4835,20 +4835,84 @@ time_load(VALUE klass, VALUE str)
 }
 
 /*
- *  <code>Time</code> is an abstraction of dates and times. Time is
- *  stored internally as the number of seconds with fraction since
- *  the <em>Epoch</em>, January 1, 1970 00:00 UTC.
- *  Also see the library modules <code>Date</code>.
- *  The <code>Time</code> class treats GMT (Greenwich Mean Time) and
- *  UTC (Coordinated Universal Time)<em>[Yes, UTC really does stand for
- *  Coordinated Universal Time. There was a committee involved.]</em>
- *  as equivalent.  GMT is the older way of referring to these
- *  baseline times but persists in the names of calls on POSIX
- *  systems.
- *
- *  All times may have fraction. Be aware of
- *  this fact when comparing times with each other---times that are
- *  apparently equal when displayed may be different when compared.
+ *  Time is an abstraction of dates and times. Time is stored internally as
+ *  the number of seconds with fraction since the _Epoch_, January 1, 1970
+ *  00:00 UTC. Also see the library modules Date. The Time class
+ *  treats GMT (Greenwich Mean Time) and UTC (Coordinated Universal Time)_[Yes,
+ *  UTC really does stand for Coordinated Universal Time. There was a committee
+ *  involved.]_ as equivalent.  GMT is the older way of referring to these
+ *  baseline times but persists in the names of calls on POSIX systems.
+ *
+ *  All times may have fraction. Be aware of this fact when comparing times
+ *  with each other--times that are apparently equal when displayed may be
+ *  different when compared.
+ *
+ *  = Examples
+ *
+ *  All of these examples were done using the EST timezone which is GMT-5.
+ *
+ *  == Creating a new Time instance
+ *
+ *  You can create a new instance of time with Time.new. This will use the
+ *  current system time. Time.now is a synonym for this. You can also
+ *  pass parts of the time to Time.new such as year, month, minute, etc. When
+ *  you want to construct a time this way you must pass at least a year. If you
+ *  pass the year with nothing else time with default to January 1 of that year
+ *  at 00:00:00 with the current system timezone. Here are some examples:
+ *
+ *    Time.new(2002)         #=> 2002-01-01 00:00:00 -0500
+ *    Time.new(2002, 10)     #=> 2002-10-01 00:00:00 -0500
+ *    Time.new(2002, 10, 31) #=> 2002-10-31 00:00:00 -0500
+ *    Time.new(2002, 10, 31, 2, 2, 2, "+02:00") #=> 2002-10-31 02:02:02 -0200
+ *
+ *  You can also use #gm, #local and #utc to infer GMT, local and UTC
+ *  timezones instead of using the current system setting.
+ *
+ *  You can also create a new time using Time.at which takes the number of
+ *  seconds (or fraction of seconds) since the Unix
+ *  Epoch[http://en.wikipedia.org/wiki/Unix_time].
+ *
+ *    Time.at(628232400) #=> 1989-11-28 00:00:00 -0500
+ *
+ *  == Working with an instance of Time
+ *
+ *  Once you have an instance of time there is a multitude of things you can do
+ *  with it. Below are some examples. For all of the following examples, we
+ *  will work on the assumption that you have done the following:
+ *
+ *    t = Time.new(1993, 02, 24, 12, 0, 0, "+09:00")
+ *
+ *  Was that a monday?
+ *  
+ *    t.monday? #=> false
+ *
+ *  What year was that again?
+ *
+ *    t.year #=> 1993
+ *
+ *  Was is daylight savings at the time?
+ *
+ *    t.dst? #=> false
+ *
+ *  What's the day a year later?
+ *
+ *    t + (60*60*24*365) #=> 1994-02-24 12:00:00 +0900
+ *
+ *  How many second was that from the Unix Epoc?
+ *
+ *    t.to_i #=> 730522800
+ *
+ *  You can also do standard functions like compare two times.
+ *
+ *    t1 = Time.new(2010)
+ *    t2 = Time.new(2011)
+ *    
+ *    t1 == t2 #=> false
+ *    t1 == t1 #=> true
+ *    t1 <  t2 #=> true
+ *    t1 >  t2 #=> false
+ *
+ *    Time.new(2010,10,31).between?(t1, t2) #=> true
  */
 
 void