[DOC] Enhanced intro for Date

ext/date/date_core.c

@@ -9378,165 +9378,158 @@ Init_date_core(void)
     negative_inf = -INFINITY;
 
     /*
-     * date and datetime class - Tadayoshi Funaba 1998-2011
-     *
-     * 'date' provides two classes: Date and DateTime.
-     *
-     * == Terms and Definitions
-     *
-     * Some terms and definitions are based on ISO 8601 and JIS X 0301.
-     *
-     * === Calendar Date
-     *
-     * The calendar date is a particular day of a calendar year,
-     * identified by its ordinal number within a calendar month within
-     * that year.
-     *
-     * In those classes, this is so-called "civil".
-     *
-     * === Ordinal Date
-     *
-     * The ordinal date is a particular day of a calendar year identified
-     * by its ordinal number within the year.
-     *
-     * In those classes, this is so-called "ordinal".
-     *
-     * === Week Date
-     *
-     * The week date is a date identified by calendar week and day numbers.
-     *
-     * The calendar week is a seven day period within a calendar year,
-     * starting on a Monday and identified by its ordinal number within
-     * the year; the first calendar week of the year is the one that
-     * includes the first Thursday of that year. In the Gregorian
-     * calendar, this is equivalent to the week which includes January 4.
-     *
-     * In those classes, this is so-called "commercial".
-     *
-     * === Julian Day Number
-     *
-     * The Julian day number is in elapsed days since noon (Greenwich Mean
-     * Time) on January 1, 4713 BCE (in the Julian calendar).
-     *
-     * In this document, the astronomical Julian day number is the same as
-     * the original Julian day number. And the chronological Julian day
-     * number is a variation of the Julian day number. Its days begin at
-     * midnight on local time.
-     *
-     * In this document, when the term "Julian day number" simply appears,
-     * it just refers to "chronological Julian day number", not the
-     * original.
-     *
-     * In those classes, those are so-called "ajd" and "jd".
-     *
-     * === Modified Julian Day Number
-     *
-     * The modified Julian day number is in elapsed days since midnight
-     * (Coordinated Universal Time) on November 17, 1858 CE (in the
-     * Gregorian calendar).
-     *
-     * In this document, the astronomical modified Julian day number is
-     * the same as the original modified Julian day number. And the
-     * chronological modified Julian day number is a variation of the
-     * modified Julian day number. Its days begin at midnight on local
-     * time.
-     *
-     * In this document, when the term "modified Julian day number" simply
-     * appears, it just refers to "chronological modified Julian day
-     * number", not the original.
-     *
-     * In those classes, those are so-called "amjd" and "mjd".
-     *
-     * == Date
-     *
-     * A subclass of Object that includes the Comparable module and
-     * easily handles date.
-     *
-     * A Date object is created with Date::new, Date::jd, Date::ordinal,
-     * Date::commercial, Date::parse, Date::strptime, Date::today,
-     * Time#to_date, etc.
-     *
-     *     require 'date'
-     *
-     *     Date.new(2001,2,3)
-     *	    #=> #<Date: 2001-02-03 ...>
-     *     Date.jd(2451944)
-     *	    #=> #<Date: 2001-02-03 ...>
-     *     Date.ordinal(2001,34)
-     *	    #=> #<Date: 2001-02-03 ...>
-     *     Date.commercial(2001,5,6)
-     *	    #=> #<Date: 2001-02-03 ...>
-     *     Date.parse('2001-02-03')
-     *	    #=> #<Date: 2001-02-03 ...>
-     *     Date.strptime('03-02-2001', '%d-%m-%Y')
-     *	    #=> #<Date: 2001-02-03 ...>
-     *     Time.new(2001,2,3).to_date
-     *	    #=> #<Date: 2001-02-03 ...>
-     *
-     * All date objects are immutable; hence cannot modify themselves.
-     *
-     * The concept of a date object can be represented as a tuple
-     * of the day count, the offset and the day of calendar reform.
-     *
-     * The day count denotes the absolute position of a temporal
-     * dimension. The offset is relative adjustment, which determines
-     * decoded local time with the day count. The day of calendar
-     * reform denotes the start day of the new style. The old style
-     * of the West is the Julian calendar which was adopted by
-     * Caesar. The new style is the Gregorian calendar, which is the
-     * current civil calendar of many countries.
-     *
-     * The day count is virtually the astronomical Julian day number.
-     * The offset in this class is usually zero, and cannot be
-     * specified directly.
-     *
-     * A Date object can be created with an optional argument,
-     * the day of calendar reform as a Julian day number, which
-     * should be 2298874 to 2426355 or negative/positive infinity.
-     * The default value is +Date::ITALY+ (2299161=1582-10-15).
-     * See also sample/cal.rb.
-     *
-     *     $ ruby sample/cal.rb -c it 10 1582
-     *         October 1582
-     *      S  M Tu  W Th  F  S
-     *         1  2  3  4 15 16
-     *     17 18 19 20 21 22 23
-     *     24 25 26 27 28 29 30
-     *     31
-     *
-     *     $ ruby sample/cal.rb -c gb  9 1752
-     *        September 1752
-     *      S  M Tu  W Th  F  S
-     *            1  2 14 15 16
-     *     17 18 19 20 21 22 23
-     *     24 25 26 27 28 29 30
-     *
-     * A Date object has various methods. See each reference.
-     *
-     *     d = Date.parse('3rd Feb 2001')
-     *					#=> #<Date: 2001-02-03 ...>
-     *     d.year			#=> 2001
-     *     d.mon			#=> 2
-     *     d.mday			#=> 3
-     *     d.wday			#=> 6
-     *     d += 1			#=> #<Date: 2001-02-04 ...>
-     *     d.strftime('%a %d %b %Y')	#=> "Sun 04 Feb 2001"
-     *
-     * === Argument +limit+
-     *
-     * Certain singleton methods in \Date that parse string arguments
-     * also take optional keyword argument +limit+,
-     * which can limit the length of the string argument.
-     *
-     * When +limit+ is:
-     *
-     * - Non-negative:
-     *   raises ArgumentError if the string length is greater than _limit_.
-     * - Other numeric or +nil+: ignores +limit+.
-     * - Other non-numeric: raises TypeError.
-     *
-     */
-
+    * \Class \Date provides methods for storing and manipulating
+    * calendar dates.
+    *
+    * Consider using
+    * {class Time}[https://docs.ruby-lang.org/en/master/Time.html]
+    * instead of class \Date if:
+    *
+    * - You need both dates and times; \Date handles only dates.
+    * - You need only Gregorian dates (and not Julian dates);
+    *   see {Julian and Gregorian Calendars}[rdoc-ref:calendars.rdoc].
+    *
+    * A \Date object, once created, is immutable, and cannot be modified.
+    *
+    * == Creating a \Date
+    *
+    * You can create a date for the current date, using Date.today:
+    *
+    *   Date.today # => #<Date: 1999-12-31>
+    *
+    * You can create a specific date from various combinations of arguments:
+    *
+    * - Date.new takes integer year, month, and day-of-month:
+    *
+    *     Date.new(1999, 12, 31) # => #<Date: 1999-12-31>
+    *
+    * - Date.ordinal takes integer year and day-of-year:
+    *
+    *     Date.ordinal(1999, 365) # => #<Date: 1999-12-31>
+    *
+    * - Date.jd takes integer Julian day:
+    *
+    *     Date.jd(2451544) # => #<Date: 1999-12-31>
+    *
+    * - Date.commercial takes integer commercial data (year, week, day-of-week):
+    *
+    *     Date.commercial(1999, 52, 5) # => #<Date: 1999-12-31>
+    *
+    * - Date.parse takes a string, which it parses heuristically:
+    *
+    *     Date.parse('1999-12-31')    # => #<Date: 1999-12-31>
+    *     Date.parse('31-12-1999')    # => #<Date: 1999-12-31>
+    *     Date.parse('1999-365')      # => #<Date: 1999-12-31>
+    *     Date.parse('1999-W52-5')    # => #<Date: 1999-12-31>
+    *
+    * - Date.strptime takes a date string and a format string,
+    *   then parses the date string according to the format string:
+    *
+    *     Date.strptime('1999-12-31', '%Y-%m-%d')  # => #<Date: 1999-12-31>
+    *     Date.strptime('31-12-1999', '%d-%m-%Y')  # => #<Date: 1999-12-31>
+    *     Date.strptime('1999-365', '%Y-%j')       # => #<Date: 1999-12-31>
+    *     Date.strptime('1999-W52-5', '%G-W%V-%u') # => #<Date: 1999-12-31>
+    *     Date.strptime('1999 52 5', '%Y %U %w')   # => #<Date: 1999-12-31>
+    *     Date.strptime('1999 52 5', '%Y %W %u')   # => #<Date: 1999-12-31>
+    *     Date.strptime('fri31dec99', '%a%d%b%y')  # => #<Date: 1999-12-31>
+    *
+    * See also the specialized methods in
+    * {Standard Format Strings}[rdoc-ref:Date@Standard+Format+Strings].
+    *
+    * == Standard Format Strings
+    *
+    * === HTTP Format
+    *
+    * The HTTP date format is based on
+    * {RFC 2616}[https://datatracker.ietf.org/doc/html/rfc2616],
+    * and treats dates in the format <tt>'%a, %d %b %Y %T GMT'</tt>;
+    * see {Formats for Dates and Times}[https://docs.ruby-lang.org/en/master/strftime_formatting_rdoc.html]:
+    *
+    *   d = Date.new(2001, 2, 3) # => #<Date: 2001-02-03>
+    *   # Return HTTP-formatted string.
+    *   httpdate = d.httpdate    # => "Sat, 03 Feb 2001 00:00:00 GMT"
+    *   # Return new date parsed from HTTP-formatted string.
+    *   Date.httpdate(httpdate)  # => #<Date: 2001-02-03>
+    *   # Return hash parsed from HTTP-formatted string.
+    *   Date._httpdate(httpdate)
+    *   # => {:wday=>6, :mday=>3, :mon=>2, :year=>2001, :hour=>0, :min=>0, :sec=>0, :zone=>"GMT", :offset=>0}
+    *
+    * === ISO 8601 Format
+    *
+    * The ISO 8601 date format is based on
+    * {ISO 8601}[https://en.wikipedia.org/wiki/ISO_8601],
+    * and treats dates in the format <tt>'%Y-%m-%d'</tt>;
+    * see {ISO 8601 Format Specifications}[https://docs.ruby-lang.org/en/master/strftime_formatting_rdoc.html#label-ISO+8601+Format+Specifications]:
+    *
+    *   d = Date.new(2001, 2, 3) # => #<Date: 2001-02-03>
+    *   # Return 8601-formatted string.
+    *   iso8601 = d.iso8601      # => "2001-02-03"
+    *   # Return new date parsed from 8601-formatted string.
+    *   Date.iso8601(iso8601)    # => #<Date: 2001-02-03>
+    *   # Return hash parsed from 8601-formatted string.
+    *   Date._iso8601(iso8601)   # => {:mday=>3, :year=>2001, :mon=>2}
+    *
+    * === RFC 3339 Format
+    *
+    * The RFC 3339 date format is based on
+    * {RFC 3339}[https://datatracker.ietf.org/doc/html/rfc3339],
+    * see {Formats for Dates and Times}[https://docs.ruby-lang.org/en/master/strftime_formatting_rdoc.html]:
+    *
+    *   d = Date.new(2001, 2, 3) # => #<Date: 2001-02-03>
+    *   # Return 3339-formatted string.
+    *   rfc3339 = d.rfc3339      # => "2001-02-03T00:00:00+00:00"
+    *   # Return new date parsed from 3339-formatted string.
+    *   Date.rfc3339(rfc3339)    # => #<Date: 2001-02-03>
+    *   # Return hash parsed from 3339-formatted string.
+    *   Date._rfc3339(rfc3339)
+    *   # => {:year=>2001, :mon=>2, :mday=>3, :hour=>0, :min=>0, :sec=>0, :zone=>"+00:00", :offset=>0}
+    *
+    * === RFC 2822 Format
+    *
+    * The RFC 2822 date format is based on
+    * {RFC 2822}[https://datatracker.ietf.org/doc/html/rfc2822],
+    * and treats dates in the format <tt>'%a, %-d %b %Y %T %z'</tt>;
+    * see {Formats for Dates and Times}[https://docs.ruby-lang.org/en/master/strftime_formatting_rdoc.html]:
+    *
+    *   d = Date.new(2001, 2, 3) # => #<Date: 2001-02-03>
+    *   # Return 2822-formatted string.
+    *   rfc2822 = d.rfc2822      # => "Sat, 3 Feb 2001 00:00:00 +0000"
+    *   # Return new date parsed from 2822-formatted string.
+    *   Date.rfc2822(rfc2822)    # => #<Date: 2001-02-03>
+    *   # Return hash parsed from 2822-formatted string.
+    *   Date._rfc2822(rfc2822)
+    *   # => {:wday=>6, :mday=>3, :mon=>2, :year=>2001, :hour=>0, :min=>0, :sec=>0, :zone=>"+0000", :offset=>0}
+    *
+    * === JIS X 0301 Format
+    *
+    * The JIS X 0301 format includes the
+    * {Japanese era name}[https://en.wikipedia.org/wiki/Japanese_era_name],
+    * and treats dates in the format <tt>'%Y-%m-%d'</tt>
+    * with the first letter of the romanized era name prefixed;
+    * see {Formats for Dates and Times}[https://docs.ruby-lang.org/en/master/strftime_formatting_rdoc.html]:
+    *
+    *   d = Date.new(2001, 2, 3) # => #<Date: 2001-02-03>
+    *   # Return 0301-formatted string.
+    *   jisx0301 = d.jisx0301    # => "H13.02.03"
+    *   # Return new date parsed from 0301-formatted string.
+    *   Date.jisx0301(jisx0301)  # => #<Date: 2001-02-03>
+    *   # Return hash parsed from 0301-formatted string.
+    *   Date._jisx0301(jisx0301) # => {:year=>2001, :mon=>2, :mday=>3}
+    *
+    * == Argument +limit+
+    *
+    * Certain singleton methods in \Date that parse string arguments
+    * also take optional keyword argument +limit+,
+    * which can limit the length of the string argument.
+    *
+    * When +limit+ is:
+    *
+    * - Non-negative:
+    *   raises ArgumentError if the string length is greater than _limit_.
+    * - Other numeric or +nil+: ignores +limit+.
+    * - Other non-numeric: raises TypeError.
+    *
+    */
     cDate = rb_define_class("Date", rb_cObject);
 
     /* Exception for invalid date/time */