[前][次][番号順一覧][スレッド一覧]

ruby-changes:42647

From: nobu <ko1@a...>
Date: Sat, 23 Apr 2016 10:24:52 +0900 (JST)
Subject: [ruby-changes:42647] nobu:r54721 (trunk): date_core.c: [DOC] markdown to rdoc [ci skip]

nobu	2016-04-23 11:21:29 +0900 (Sat, 23 Apr 2016)

  New Revision: 54721

  https://svn.ruby-lang.org/cgi-bin/viewvc.cgi?view=revision&revision=54721

  Log:
    date_core.c: [DOC] markdown to rdoc [ci skip]
    
    * ext/date/date_core.c (Init_date_core): [DOC] Convert DateTime
      documentation to RDoc from Markdown.
      [ruby-core:75136] [Bug #12311]

  Modified files:
    trunk/ChangeLog
    trunk/ext/date/date_core.c
Index: ChangeLog
===================================================================
--- ChangeLog	(revision 54720)
+++ ChangeLog	(revision 54721)
@@ -1,3 +1,9 @@ https://github.com/ruby/ruby/blob/trunk/ChangeLog#L1
+Sat Apr 23 11:21:27 2016  Marcus Stollsteimer  <sto.mar@w...>
+
+	* ext/date/date_core.c (Init_date_core): [DOC] Convert DateTime
+	  documentation to RDoc from Markdown.
+	  [ruby-core:75136] [Bug #12311]
+
 Sat Apr 23 09:03:35 2016  Nobuyoshi Nakada  <nobu@r...>
 
 	* ruby.c: cygwin does not use w32_cmdvector, command line can be
Index: ext/date/date_core.c
===================================================================
--- ext/date/date_core.c	(revision 54720)
+++ ext/date/date_core.c	(revision 54721)
@@ -9394,154 +9394,142 @@ Init_date_core(void) https://github.com/ruby/ruby/blob/trunk/ext/date/date_core.c#L9394
     rb_define_singleton_method(cDate, "_load", date_s__load, 1);
 
     /*
-	:markup: Markdown
-
-	## DateTime
-
-	A subclass of Date that easily handles date, hour, minute, second and
-	offset.
-
-	DateTime does not consider any leap seconds, does not track
-	any summer time rules.
-
-	DateTime object is created with DateTime::new, DateTime::jd,
-	DateTime::ordinal, DateTime::commercial, DateTime::parse,
-	DateTime::strptime, DateTime::now, Time#to_datetime or etc.
-
-	    require 'date'
-
-	    DateTime.new(2001,2,3,4,5,6)
-				#=> #<DateTime: 2001-02-03T04:05:06+00:00 ...>
-
-	The last element of day, hour, minute or second can be
-	fractional number. The fractional number's precision is assumed
-	at most nanosecond.
-
-	    DateTime.new(2001,2,3.5)
-				#=> #<DateTime: 2001-02-03T12:00:00+00:00 ...>
-
-	An optional argument the offset indicates the difference
-	between the local time and UTC. For example, `Rational(3,24)`
-	represents ahead of 3 hours of UTC, `Rational(-5,24)` represents
-	behind of 5 hours of UTC. The offset should be -1 to +1, and
-	its precision is assumed at most second. The default value is
-	zero(equals to UTC).
-
-	    DateTime.new(2001,2,3,4,5,6,Rational(3,24))
-				#=> #<DateTime: 2001-02-03T04:05:06+03:00 ...>
-
-	also accepts string form.
-
-	    DateTime.new(2001,2,3,4,5,6,'+03:00')
-				#=> #<DateTime: 2001-02-03T04:05:06+03:00 ...>
-
-	An optional argument the day of calendar reform (start) denotes
-	a Julian day number, which should be 2298874 to 2426355 or
-	-/+oo.  The default value is `Date::ITALY` (2299161=1582-10-15).
-
-	DateTime object has various methods. See each reference.
-
-	    d = DateTime.parse('3rd Feb 2001 04:05:06+03:30')
-				#=> #<DateTime: 2001-02-03T04:05:06+03:30 ...>
-	    d.hour		#=> 4
-	    d.min		#=> 5
-	    d.sec		#=> 6
-	    d.offset		#=> (7/48)
-	    d.zone		#=> "+03:30"
-	    d += Rational('1.5')
-				#=> #<DateTime: 2001-02-04%16:05:06+03:30 ...>
-	    d = d.new_offset('+09:00')
-				#=> #<DateTime: 2001-02-04%21:35:06+09:00 ...>
-	    d.strftime('%I:%M:%S %p')
-				#=> "09:35:06 PM"
-	    d > DateTime.new(1999)
-				#=> true
-
-	### When should you use DateTime and when should you use Time?
-
-	It's a common misconception that [William Shakespeare][1] and
-	[Miguel de Cervantes][2] died on the same day in history -
-	so much so that UNESCO named April 23 as [World Book Day
-	because of this fact][3].
-	However because England hadn't yet adopted [Gregorian Calendar
-	Reform][4] (and wouldn't until [1752][5]) their deaths are
-	actually 10 days apart. Since Ruby's `Time` class implements a
-	[proleptic Gregorian calendar][6] and has no concept of
-	calendar reform then there's no way to express this. This is
-	where `DateTime` steps in:
-
-	``` irb
-	>> shakespeare = DateTime.iso8601('1616-04-23', Date::ENGLAND)
-	=> Tue, 23 Apr 1616 00:00:00 +0000
-	>> cervantes = DateTime.iso8601('1616-04-23', Date::ITALY)
-	=> Sat, 23 Apr 1616 00:00:00 +0000
-	```
-
-	Already you can see something's weird - the days of the week
-	are different, taking this further:
-
-	``` irb
-	>> cervantes == shakespeare
-	=> false
-	>> (shakespeare - cervantes).to_i
-	=> 10
-	```
-
-	This shows that in fact they died 10 days apart (in reality 11
-	days since Cervantes died a day earlier but was buried on the
-	23rd). We can see the actual date of Shakespeare's death by
-	using the `gregorian` method to convert it:
-
-	``` irb
-	>> shakespeare.gregorian
-	=> Tue, 03 May 1616 00:00:00 +0000
-	```
-
-	So there's an argument that all the celebrations that take
-	place on the 23rd April in Stratford-upon-Avon are actually
-	the wrong date since England is now using the Gregorian
-	calendar. You can see why when we transition across the reform
-	date boundary:
-
-	``` irb
-	# start off with the anniversary of Shakespeare's birth in 1751
-	>> shakespeare = DateTime.iso8601('1751-04-23', Date::ENGLAND)
-	=> Tue, 23 Apr 1751 00:00:00 +0000
-
-	# add 366 days since 1752 is a leap year and April 23 is after February 29
-	>> shakespeare + 366
-	=> Thu, 23 Apr 1752 00:00:00 +0000
-
-	# add another 365 days to take us to the anniversary in 1753
-	>> shakespeare + 366 + 365
-	=> Fri, 04 May 1753 00:00:00 +0000
-	```
-
-	As you can see, if we're accurately tracking the number of
-	[solar years][9] since Shakespeare's birthday then the correct
-	anniversary date would be the 4th May and not the 23rd April.
-
-	So when should you use `DateTime` in Ruby and when should
-	you use `Time`? Almost certainly you'll want to use `Time`
-	since your app is probably dealing with current dates and
-	times. However, if you need to deal with dates and times in a
-	historical context you'll want to use `DateTime` to avoid
-	making the same mistakes as UNESCO. If you also have to deal
-	with timezones then best of luck - just bear in mind that
-	you'll probably be dealing with [local solar times][7], since
-	it wasn't until the 19th century that the introduction of the
-	railways necessitated the need for [Standard Time][8] and
-	eventually timezones.
-
-	[1]: http://en.wikipedia.org/wiki/William_Shakespeare
-	[2]: http://en.wikipedia.org/wiki/Miguel_de_Cervantes
-	[3]: http://en.wikipedia.org/wiki/World_Book_Day
-	[4]: http://en.wikipedia.org/wiki/Gregorian_calendar#Gregorian_reform
-	[5]: http://en.wikipedia.org/wiki/Calendar_(New_Style)_Act_1750
-	[6]: http://en.wikipedia.org/wiki/Proleptic_Gregorian_calendar
-	[7]: http://en.wikipedia.org/wiki/Solar_time
-	[8]: http://en.wikipedia.org/wiki/Standard_time#Great_Britain
-	[9]: http://en.wikipedia.org/wiki/Tropical_year
+     * == DateTime
+     *
+     * A subclass of Date that easily handles date, hour, minute, second and
+     * offset.
+     *
+     * DateTime does not consider any leap seconds, does not track
+     * any summer time rules.
+     *
+     * DateTime object is created with DateTime::new, DateTime::jd,
+     * DateTime::ordinal, DateTime::commercial, DateTime::parse,
+     * DateTime::strptime, DateTime::now, Time#to_datetime or etc.
+     *
+     *     require 'date'
+     *
+     *     DateTime.new(2001,2,3,4,5,6)
+     *                         #=> #<DateTime: 2001-02-03T04:05:06+00:00 ...>
+     *
+     * The last element of day, hour, minute or second can be
+     * fractional number. The fractional number's precision is assumed
+     * at most nanosecond.
+     *
+     *     DateTime.new(2001,2,3.5)
+     *                         #=> #<DateTime: 2001-02-03T12:00:00+00:00 ...>
+     *
+     * An optional argument the offset indicates the difference
+     * between the local time and UTC. For example, <tt>Rational(3,24)</tt>
+     * represents ahead of 3 hours of UTC, <tt>Rational(-5,24)</tt> represents
+     * behind of 5 hours of UTC. The offset should be -1 to +1, and
+     * its precision is assumed at most second. The default value is
+     * zero(equals to UTC).
+     *
+     *     DateTime.new(2001,2,3,4,5,6,Rational(3,24))
+     *                         #=> #<DateTime: 2001-02-03T04:05:06+03:00 ...>
+     *
+     * also accepts string form.
+     *
+     *     DateTime.new(2001,2,3,4,5,6,'+03:00')
+     *                         #=> #<DateTime: 2001-02-03T04:05:06+03:00 ...>
+     *
+     * An optional argument the day of calendar reform (start) denotes
+     * a Julian day number, which should be 2298874 to 2426355 or
+     * -/+oo.  The default value is +Date::ITALY+ (2299161=1582-10-15).
+     *
+     * DateTime object has various methods. See each reference.
+     *
+     *     d = DateTime.parse('3rd Feb 2001 04:05:06+03:30')
+     *                         #=> #<DateTime: 2001-02-03T04:05:06+03:30 ...>
+     *     d.hour              #=> 4
+     *     d.min               #=> 5
+     *     d.sec               #=> 6
+     *     d.offset            #=> (7/48)
+     *     d.zone              #=> "+03:30"
+     *     d += Rational('1.5')
+     *                         #=> #<DateTime: 2001-02-04%16:05:06+03:30 ...>
+     *     d = d.new_offset('+09:00')
+     *                         #=> #<DateTime: 2001-02-04%21:35:06+09:00 ...>
+     *     d.strftime('%I:%M:%S %p')
+     *                         #=> "09:35:06 PM"
+     *     d > DateTime.new(1999)
+     *                         #=> true
+     *
+     * === When should you use DateTime and when should you use Time?
+     *
+     * It's a common misconception that
+     * {William Shakespeare}[http://en.wikipedia.org/wiki/William_Shakespeare]
+     * and
+     * {Miguel de Cervantes}[http://en.wikipedia.org/wiki/Miguel_de_Cervantes]
+     * died on the same day in history -
+     * so much so that UNESCO named April 23 as
+     * {World Book Day because of this fact}[http://en.wikipedia.org/wiki/World_Book_Day].
+     * However because England hadn't yet adopted
+     * {Gregorian Calendar Reform}[http://en.wikipedia.org/wiki/Gregorian_calendar#Gregorian_reform]
+     * (and wouldn't until {1752}[http://en.wikipedia.org/wiki/Calendar_(New_Style)_Act_1750])
+     * their deaths are actually 10 days apart.
+     * Since Ruby's Time class implements a
+     * {proleptic Gregorian calendar}[http://en.wikipedia.org/wiki/Proleptic_Gregorian_calendar]
+     * and has no concept of calendar reform then there's no way
+     * to express this. This is where DateTime steps in:
+     *
+     *     shakespeare = DateTime.iso8601('1616-04-23', Date::ENGLAND)
+     *      #=> Tue, 23 Apr 1616 00:00:00 +0000
+     *     cervantes = DateTime.iso8601('1616-04-23', Date::ITALY)
+     *      #=> Sat, 23 Apr 1616 00:00:00 +0000
+     *
+     * Already you can see something's weird - the days of the week
+     * are different, taking this further:
+     *
+     *     cervantes == shakespeare
+     *      #=> false
+     *     (shakespeare - cervantes).to_i
+     *      #=> 10
+     *
+     * This shows that in fact they died 10 days apart (in reality
+     * 11 days since Cervantes died a day earlier but was buried on
+     * the 23rd). We can see the actual date of Shakespeare's death by
+     * using the #gregorian method to convert it:
+     *
+     *     shakespeare.gregorian
+     *      #=> Tue, 03 May 1616 00:00:00 +0000
+     *
+     * So there's an argument that all the celebrations that take
+     * place on the 23rd April in Stratford-upon-Avon are actually
+     * the wrong date since England is now using the Gregorian calendar.
+     * You can see why when we transition across the reform
+     * date boundary:
+     *
+     *     # start off with the anniversary of Shakespeare's birth in 1751
+     *     shakespeare = DateTime.iso8601('1751-04-23', Date::ENGLAND)
+     *      #=> Tue, 23 Apr 1751 00:00:00 +0000
+     *
+     *     # add 366 days since 1752 is a leap year and April 23 is after February 29
+     *     shakespeare + 366
+     *      #=> Thu, 23 Apr 1752 00:00:00 +0000
+     *
+     *     # add another 365 days to take us to the anniversary in 1753
+     *     shakespeare + 366 + 365
+     *      #=> Fri, 04 May 1753 00:00:00 +0000
+     *
+     * As you can see, if we're accurately tracking the number of
+     * {solar years}[http://en.wikipedia.org/wiki/Tropical_year]
+     * since Shakespeare's birthday then the correct anniversary date
+     * would be the 4th May and not the 23rd April.
+     *
+     * So when should you use DateTime in Ruby and when should
+     * you use Time? Almost certainly you'll want to use Time
+     * since your app is probably dealing with current dates and
+     * times. However, if you need to deal with dates and times in a
+     * historical context you'll want to use DateTime to avoid
+     * making the same mistakes as UNESCO. If you also have to deal
+     * with timezones then best of luck - just bear in mind that
+     * you'll probably be dealing with
+     * {local solar times}[http://en.wikipedia.org/wiki/Solar_time],
+     * since it wasn't until the 19th century that the introduction
+     * of the railways necessitated the need for
+     * {Standard Time}[http://en.wikipedia.org/wiki/Standard_time#Great_Britain]
+     * and eventually timezones.
      */
 
     cDateTime = rb_define_class("DateTime", cDate);

--
ML: ruby-changes@q...
Info: http://www.atdot.net/~ko1/quickml/

[前][次][番号順一覧][スレッド一覧]