rbs 2.8.4 → 3.8.1

data/stdlib/date/0/date.rbs

@@ -1,144 +1,96 @@
 # <!-- rdoc-file=ext/date/date_core.c -->
-# date and datetime class - Tadayoshi Funaba 1998-2011
+# Class Date provides methods for storing and manipulating calendar dates.
 #
-# 'date' provides two classes: Date and DateTime.
+# Consider using [class Time](rdoc-ref:Time) instead of class Date if:
 #
-# ## Terms and Definitions
+# *   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:date/calendars.rdoc).
 #
-# Some terms and definitions are based on ISO 8601 and JIS X 0301.
+# A Date object, once created, is immutable, and cannot be modified.
 #
-# ### Calendar Date
+# ## Creating a Date
 #
-# The calendar date is a particular day of a calendar year, identified by its
-# ordinal number within a calendar month within that year.
+# You can create a date for the current date, using Date.today:
 #
-# In those classes, this is so-called "civil".
+#     Date.today # => #<Date: 1999-12-31>
 #
-# ### Ordinal Date
+# You can create a specific date from various combinations of arguments:
 #
-# The ordinal date is a particular day of a calendar year identified by its
-# ordinal number within the year.
+# *   Date.new takes integer year, month, and day-of-month:
 #
-# In those classes, this is so-called "ordinal".
+#         Date.new(1999, 12, 31) # => #<Date: 1999-12-31>
 #
-# ### Week Date
+# *   Date.ordinal takes integer year and day-of-year:
 #
-# The week date is a date identified by calendar week and day numbers.
+#         Date.ordinal(1999, 365) # => #<Date: 1999-12-31>
 #
-# 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.
+# *   Date.jd takes integer Julian day:
 #
-# In those classes, this is so-called "commercial".
+#         Date.jd(2451544) # => #<Date: 1999-12-31>
 #
-# ### Julian Day Number
+# *   Date.commercial takes integer commercial data (year, week, day-of-week):
 #
-# The Julian day number is in elapsed days since noon (Greenwich Mean Time) on
-# January 1, 4713 BCE (in the Julian calendar).
+#         Date.commercial(1999, 52, 5) # => #<Date: 1999-12-31>
 #
-# 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.
+# *   Date.parse takes a string, which it parses heuristically:
 #
-# In this document, when the term "Julian day number" simply appears, it just
-# refers to "chronological Julian day number", not the original.
+#         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>
 #
-# In those classes, those are so-called "ajd" and "jd".
+# *   Date.strptime takes a date string and a format string, then parses the
+#     date string according to the format string:
 #
-# ### Modified Julian Day Number
+#         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>
 #
-# The modified Julian day number is in elapsed days since midnight (Coordinated
-# Universal Time) on November 17, 1858 CE (in the Gregorian calendar).
+# See also the specialized methods in ["Specialized Format Strings" in Formats
+# for Dates and
+# Times](rdoc-ref:strftime_formatting.rdoc@Specialized+Format+Strings)
 #
-# 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.
+# ## Argument `limit`
 #
-# In this document, when the term "modified Julian day number" simply appears,
-# it just refers to "chronological modified Julian day number", not the
-# original.
+# Certain singleton methods in Date that parse string arguments also take
+# optional keyword argument `limit`, which can limit the length of the string
+# argument.
 #
-# In those classes, those are so-called "amjd" and "mjd".
+# When `limit` is:
 #
-# ## 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"
+# *   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
   # <!--
   #   rdoc-file=ext/date/date_core.c
-  #   - new(p1 = v1, p2 = v2, p3 = v3, p4 = v4)
+  #   - Date.new(year = -4712, month = 1, mday = 1, start = Date::ITALY) -> date
   # -->
+  # Returns a new Date object constructed from the given arguments:
+  #
+  #     Date.new(2022).to_s        # => "2022-01-01"
+  #     Date.new(2022, 2).to_s     # => "2022-02-01"
+  #     Date.new(2022, 2, 4).to_s  # => "2022-02-04"
+  #
+  # Argument `month` should be in range (1..12) or range (-12..-1); when the
+  # argument is negative, counts backward from the end of the year:
+  #
+  #     Date.new(2022, -11, 4).to_s # => "2022-02-04"
+  #
+  # Argument `mday` should be in range (1..n) or range (-n..-1) where `n` is the
+  # number of days in the month; when the argument is negative, counts backward
+  # from the end of the month.
+  #
+  # See argument [start](rdoc-ref:date/calendars.rdoc@Argument+start).
+  #
+  # Related: Date.jd.
   #
   def initialize: (?Integer year, ?Integer month, ?Integer mday, ?Integer start) -> void
 
@@ -146,485 +98,629 @@ class Date
 
   # <!--
   #   rdoc-file=ext/date/date_core.c
-  #   - Date._httpdate(string, limit: 128)  ->  hash
+  #   - Date._httpdate(string, limit: 128) -> hash
   # -->
-  # Returns a hash of parsed elements.
+  # Returns a hash of values parsed from `string`, which should be a valid [HTTP
+  # date format](rdoc-ref:strftime_formatting.rdoc@HTTP+Format):
+  #
+  #     d = Date.new(2001, 2, 3)
+  #     s = d.httpdate # => "Sat, 03 Feb 2001 00:00:00 GMT"
+  #     Date._httpdate(s)
+  #     # => {:wday=>6, :mday=>3, :mon=>2, :year=>2001, :hour=>0, :min=>0, :sec=>0, :zone=>"GMT", :offset=>0}
   #
-  # Raise an ArgumentError when the string length is longer than *limit*. You can
-  # stop this check by passing `limit: nil`, but note that it may take a long time
-  # to parse.
+  # Related: Date.httpdate (returns a Date object).
   #
   def self._httpdate: (String str) -> Hash[Symbol, Integer]
 
   # <!--
   #   rdoc-file=ext/date/date_core.c
-  #   - Date._iso8601(string, limit: 128)  ->  hash
+  #   - Date._iso8601(string, limit: 128) -> hash
   # -->
-  # Returns a hash of parsed elements.
+  # Returns a hash of values parsed from `string`, which should contain an [ISO
+  # 8601 formatted
+  # date](rdoc-ref:strftime_formatting.rdoc@ISO+8601+Format+Specifications):
   #
-  # Raise an ArgumentError when the string length is longer than *limit*. You can
-  # stop this check by passing `limit: nil`, but note that it may take a long time
-  # to parse.
+  #     d = Date.new(2001, 2, 3)
+  #     s = d.iso8601    # => "2001-02-03"
+  #     Date._iso8601(s) # => {:mday=>3, :year=>2001, :mon=>2}
+  #
+  # See argument [limit](rdoc-ref:Date@Argument+limit).
+  #
+  # Related: Date.iso8601 (returns a Date object).
   #
   def self._iso8601: (String str) -> Hash[Symbol, Integer]
 
   # <!--
   #   rdoc-file=ext/date/date_core.c
-  #   - Date._jisx0301(string, limit: 128)  ->  hash
+  #   - Date._jisx0301(string, limit: 128) -> hash
   # -->
-  # Returns a hash of parsed elements.
+  # Returns a hash of values parsed from `string`, which should be a valid [JIS X
+  # 0301 date format](rdoc-ref:strftime_formatting.rdoc@JIS+X+0301+Format):
+  #
+  #     d = Date.new(2001, 2, 3)
+  #     s = d.jisx0301    # => "H13.02.03"
+  #     Date._jisx0301(s) # => {:year=>2001, :mon=>2, :mday=>3}
   #
-  # Raise an ArgumentError when the string length is longer than *limit*. You can
-  # stop this check by passing `limit: nil`, but note that it may take a long time
-  # to parse.
+  # See argument [limit](rdoc-ref:Date@Argument+limit).
+  #
+  # Related: Date.jisx0301 (returns a Date object).
   #
   def self._jisx0301: (String str) -> Hash[Symbol, Integer]
 
   # <!--
   #   rdoc-file=ext/date/date_core.c
-  #   - Date._parse(string[, comp=true], limit: 128)  ->  hash
+  #   - Date._parse(string, comp = true, limit: 128) -> hash
   # -->
-  # Parses the given representation of date and time, and returns a hash of parsed
-  # elements.
+  # **Note**: This method recognizes many forms in `string`, but it is not a
+  # validator. For formats, see ["Specialized Format Strings" in Formats for Dates
+  # and Times](rdoc-ref:strftime_formatting.rdoc@Specialized+Format+Strings)
+  #
+  # If `string` does not specify a valid date, the result is unpredictable;
+  # consider using Date._strptime instead.
   #
-  # This method *does not* function as a validator.  If the input string does not
-  # match valid formats strictly, you may get a cryptic result.  Should consider
-  # to use `Date._strptime` or `DateTime._strptime` instead of this method as
-  # possible.
+  # Returns a hash of values parsed from `string`:
   #
-  # If the optional second argument is true and the detected year is in the range
-  # "00" to "99", considers the year a 2-digit form and makes it full.
+  #     Date._parse('2001-02-03') # => {:year=>2001, :mon=>2, :mday=>3}
   #
-  #     Date._parse('2001-02-03') #=> {:year=>2001, :mon=>2, :mday=>3}
+  # If `comp` is `true` and the given year is in the range `(0..99)`, the current
+  # century is supplied; otherwise, the year is taken as given:
   #
-  # Raise an ArgumentError when the string length is longer than *limit*. You can
-  # stop this check by passing `limit: nil`, but note that it may take a long time
-  # to parse.
+  #     Date._parse('01-02-03', true)  # => {:year=>2001, :mon=>2, :mday=>3}
+  #     Date._parse('01-02-03', false) # => {:year=>1, :mon=>2, :mday=>3}
+  #
+  # See argument [limit](rdoc-ref:Date@Argument+limit).
+  #
+  # Related: Date.parse(returns a Date object).
   #
   def self._parse: (String str, ?boolish complete) -> Hash[Symbol, Integer]
 
   # <!--
   #   rdoc-file=ext/date/date_core.c
-  #   - Date._rfc2822(string, limit: 128)  ->  hash
-  #   - Date._rfc822(string, limit: 128)   ->  hash
+  #   - Date._rfc2822(string, limit: 128) -> hash
   # -->
-  # Returns a hash of parsed elements.
+  # Returns a hash of values parsed from `string`, which should be a valid [RFC
+  # 2822 date format](rdoc-ref:strftime_formatting.rdoc@RFC+2822+Format):
+  #
+  #     d = Date.new(2001, 2, 3)
+  #     s = d.rfc2822 # => "Sat, 3 Feb 2001 00:00:00 +0000"
+  #     Date._rfc2822(s)
+  #     # => {:wday=>6, :mday=>3, :mon=>2, :year=>2001, :hour=>0, :min=>0, :sec=>0, :zone=>"+0000", :offset=>0}
   #
-  # Raise an ArgumentError when the string length is longer than *limit*. You can
-  # stop this check by passing `limit: nil`, but note that it may take a long time
-  # to parse.
+  # See argument [limit](rdoc-ref:Date@Argument+limit).
+  #
+  # Related: Date.rfc2822 (returns a Date object).
   #
   def self._rfc2822: (String str) -> Hash[Symbol, Integer | String]
 
   # <!--
   #   rdoc-file=ext/date/date_core.c
-  #   - Date._rfc3339(string, limit: 128)  ->  hash
+  #   - Date._rfc3339(string, limit: 128) -> hash
   # -->
-  # Returns a hash of parsed elements.
+  # Returns a hash of values parsed from `string`, which should be a valid [RFC
+  # 3339 format](rdoc-ref:strftime_formatting.rdoc@RFC+3339+Format):
+  #
+  #     d = Date.new(2001, 2, 3)
+  #     s = d.rfc3339     # => "2001-02-03T00:00:00+00:00"
+  #     Date._rfc3339(s)
+  #     # => {:year=>2001, :mon=>2, :mday=>3, :hour=>0, :min=>0, :sec=>0, :zone=>"+00:00", :offset=>0}
   #
-  # Raise an ArgumentError when the string length is longer than *limit*. You can
-  # stop this check by passing `limit: nil`, but note that it may take a long time
-  # to parse.
+  # See argument [limit](rdoc-ref:Date@Argument+limit).
+  #
+  # Related: Date.rfc3339 (returns a Date object).
   #
   def self._rfc3339: (String str) -> Hash[Symbol, Integer | String]
 
   # <!--
   #   rdoc-file=ext/date/date_core.c
-  #   - Date._rfc2822(string, limit: 128)  ->  hash
-  #   - Date._rfc822(string, limit: 128)   ->  hash
+  #   - Date._rfc2822(string, limit: 128) -> hash
   # -->
-  # Returns a hash of parsed elements.
+  # Returns a hash of values parsed from `string`, which should be a valid [RFC
+  # 2822 date format](rdoc-ref:strftime_formatting.rdoc@RFC+2822+Format):
+  #
+  #     d = Date.new(2001, 2, 3)
+  #     s = d.rfc2822 # => "Sat, 3 Feb 2001 00:00:00 +0000"
+  #     Date._rfc2822(s)
+  #     # => {:wday=>6, :mday=>3, :mon=>2, :year=>2001, :hour=>0, :min=>0, :sec=>0, :zone=>"+0000", :offset=>0}
+  #
+  # See argument [limit](rdoc-ref:Date@Argument+limit).
   #
-  # Raise an ArgumentError when the string length is longer than *limit*. You can
-  # stop this check by passing `limit: nil`, but note that it may take a long time
-  # to parse.
+  # Related: Date.rfc2822 (returns a Date object).
   #
   def self._rfc822: (String str) -> Hash[Symbol, Integer | String]
 
   # <!--
   #   rdoc-file=ext/date/date_core.c
-  #   - Date._strptime(string[, format='%F'])  ->  hash
+  #   - Date._strptime(string, format = '%F') -> hash
   # -->
-  # Parses the given representation of date and time with the given template, and
-  # returns a hash of parsed elements.  _strptime does not support specification
-  # of flags and width unlike strftime.
+  # Returns a hash of values parsed from `string` according to the given `format`:
+  #
+  #     Date._strptime('2001-02-03', '%Y-%m-%d') # => {:year=>2001, :mon=>2, :mday=>3}
+  #
+  # For other formats, see [Formats for Dates and
+  # Times](rdoc-ref:strftime_formatting.rdoc). (Unlike Date.strftime, does not
+  # support flags and width.)
   #
-  #     Date._strptime('2001-02-03', '%Y-%m-%d')
-  #                               #=> {:year=>2001, :mon=>2, :mday=>3}
+  # See also [strptime(3)](https://man7.org/linux/man-pages/man3/strptime.3.html).
   #
-  # See also strptime(3) and #strftime.
+  # Related: Date.strptime (returns a Date object).
   #
   def self._strptime: (String str, ?String format) -> Hash[Symbol, Integer]
 
   # <!--
   #   rdoc-file=ext/date/date_core.c
-  #   - Date._xmlschema(string, limit: 128)  ->  hash
+  #   - Date._xmlschema(string, limit: 128) -> hash
   # -->
-  # Returns a hash of parsed elements.
+  # Returns a hash of values parsed from `string`, which should be a valid XML
+  # date format:
   #
-  # Raise an ArgumentError when the string length is longer than *limit*. You can
-  # stop this check by passing `limit: nil`, but note that it may take a long time
-  # to parse.
+  #     d = Date.new(2001, 2, 3)
+  #     s = d.xmlschema    # => "2001-02-03"
+  #     Date._xmlschema(s) # => {:year=>2001, :mon=>2, :mday=>3}
+  #
+  # See argument [limit](rdoc-ref:Date@Argument+limit).
+  #
+  # Related: Date.xmlschema (returns a Date object).
   #
   def self._xmlschema: (String str) -> Hash[Symbol, Integer]
 
   # <!--
   #   rdoc-file=ext/date/date_core.c
-  #   - Date.civil([year=-4712[, month=1[, mday=1[, start=Date::ITALY]]]])  ->  date
-  #   - Date.new([year=-4712[, month=1[, mday=1[, start=Date::ITALY]]]])    ->  date
+  #   - civil(*args)
   # -->
-  # Creates a date object denoting the given calendar date.
-  #
-  # In this class, BCE years are counted astronomically.  Thus, the year before
-  # the year 1 is the year zero, and the year preceding the year zero is the year
-  # -1.  The month and the day of month should be a negative or a positive number
-  # (as a relative month/day from the end of year/month when negative).  They
-  # should not be zero.
-  #
-  # The last argument should be a Julian day number which denotes the day of
-  # calendar reform.  Date::ITALY (2299161=1582-10-15), Date::ENGLAND
-  # (2361222=1752-09-14), Date::GREGORIAN (the proleptic Gregorian calendar) and
-  # Date::JULIAN (the proleptic Julian calendar) can be specified as a day of
-  # calendar reform.
-  #
-  #     Date.new(2001)            #=> #<Date: 2001-01-01 ...>
-  #     Date.new(2001,2,3)        #=> #<Date: 2001-02-03 ...>
-  #     Date.new(2001,2,-1)       #=> #<Date: 2001-02-28 ...>
-  #
-  # See also ::jd.
+  # Same as Date.new.
   #
   def self.civil: (?Integer year, ?Integer month, ?Integer mday, ?Integer start) -> Date
 
   # <!--
   #   rdoc-file=ext/date/date_core.c
-  #   - Date.commercial([cwyear=-4712[, cweek=1[, cwday=1[, start=Date::ITALY]]]])  ->  date
+  #   - Date.commercial(cwyear = -4712, cweek = 1, cwday = 1, start = Date::ITALY) -> date
   # -->
-  # Creates a date object denoting the given week date.
+  # Returns a new Date object constructed from the arguments.
+  #
+  # Argument `cwyear` gives the year, and should be an integer.
+  #
+  # Argument `cweek` gives the index of the week within the year, and should be in
+  # range (1..53) or (-53..-1); in some years, 53 or -53 will be out-of-range; if
+  # negative, counts backward from the end of the year:
+  #
+  #     Date.commercial(2022, 1, 1).to_s  # => "2022-01-03"
+  #     Date.commercial(2022, 52, 1).to_s # => "2022-12-26"
+  #
+  # Argument `cwday` gives the indes of the weekday within the week, and should be
+  # in range (1..7) or (-7..-1); 1 or -7 is Monday; if negative, counts backward
+  # from the end of the week:
+  #
+  #     Date.commercial(2022, 1, 1).to_s  # => "2022-01-03"
+  #     Date.commercial(2022, 1, -7).to_s # => "2022-01-03"
+  #
+  # When `cweek` is 1:
+  #
+  # *   If January 1 is a Friday, Saturday, or Sunday, the first week begins in
+  #     the week after:
+  #
+  #         Date::ABBR_DAYNAMES[Date.new(2023, 1, 1).wday] # => "Sun"
+  #         Date.commercial(2023, 1, 1).to_s # => "2023-01-02"
+  #         Date.commercial(2023, 1, 7).to_s # => "2023-01-08"
   #
-  # The week and the day of week should be a negative or a positive number (as a
-  # relative week/day from the end of year/week when negative).  They should not
-  # be zero.
+  # *   Otherwise, the first week is the week of January 1, which may mean some of
+  #     the days fall on the year before:
   #
-  #     Date.commercial(2001)     #=> #<Date: 2001-01-01 ...>
-  #     Date.commercial(2002)     #=> #<Date: 2001-12-31 ...>
-  #     Date.commercial(2001,5,6) #=> #<Date: 2001-02-03 ...>
+  #         Date::ABBR_DAYNAMES[Date.new(2020, 1, 1).wday] # => "Wed"
+  #         Date.commercial(2020, 1, 1).to_s # => "2019-12-30"
+  #         Date.commercial(2020, 1, 7).to_s # => "2020-01-05"
   #
-  # See also ::jd and ::new.
+  # See argument [start](rdoc-ref:date/calendars.rdoc@Argument+start).
+  #
+  # Related: Date.jd, Date.new, Date.ordinal.
   #
   def self.commercial: (?Integer cwyear, ?Integer cweek, ?Integer cwday, ?Integer start) -> Date
 
   # <!--
   #   rdoc-file=ext/date/date_core.c
-  #   - Date.gregorian_leap?(year)  ->  bool
-  #   - Date.leap?(year)            ->  bool
+  #   - Date.gregorian_leap?(year) -> true or false
   # -->
-  # Returns true if the given year is a leap year of the proleptic Gregorian
-  # calendar.
+  # Returns `true` if the given year is a leap year in the [proleptic Gregorian
+  # calendar](https://en.wikipedia.org/wiki/Proleptic_Gregorian_calendar), `false`
+  # otherwise:
+  #
+  #     Date.gregorian_leap?(2000) # => true
+  #     Date.gregorian_leap?(2001) # => false
   #
-  #     Date.gregorian_leap?(1900)        #=> false
-  #     Date.gregorian_leap?(2000)        #=> true
+  # Related: Date.julian_leap?.
   #
   def self.gregorian_leap?: (Integer year) -> bool
 
   # <!--
   #   rdoc-file=ext/date/date_core.c
-  #   - Date.httpdate(string='Mon, 01 Jan -4712 00:00:00 GMT'[, start=Date::ITALY], limit: 128)  ->  date
+  #   - Date.httpdate(string = 'Mon, 01 Jan -4712 00:00:00 GMT', start = Date::ITALY, limit: 128) -> date
   # -->
-  # Creates a new Date object by parsing from a string according to some RFC 2616
-  # format.
+  # Returns a new Date object with values parsed from `string`, which should be a
+  # valid [HTTP date format](rdoc-ref:strftime_formatting.rdoc@HTTP+Format):
+  #
+  #     d = Date.new(2001, 2, 3)
+  #     s = d.httpdate   # => "Sat, 03 Feb 2001 00:00:00 GMT"
+  #     Date.httpdate(s) # => #<Date: 2001-02-03>
   #
-  #     Date.httpdate('Sat, 03 Feb 2001 00:00:00 GMT')
-  #                                               #=> #<Date: 2001-02-03 ...>
+  # See:
   #
-  # Raise an ArgumentError when the string length is longer than *limit*. You can
-  # stop this check by passing `limit: nil`, but note that it may take a long time
-  # to parse.
+  # *   Argument [start](rdoc-ref:date/calendars.rdoc@Argument+start).
+  # *   Argument [limit](rdoc-ref:Date@Argument+limit).
+  #
+  # Related: Date._httpdate (returns a hash).
   #
   def self.httpdate: (String str, ?Integer start) -> Date
 
   # <!--
   #   rdoc-file=ext/date/date_core.c
-  #   - Date.iso8601(string='-4712-01-01'[, start=Date::ITALY], limit: 128)  ->  date
+  #   - Date.iso8601(string = '-4712-01-01', start = Date::ITALY, limit: 128) -> date
   # -->
-  # Creates a new Date object by parsing from a string according to some typical
-  # ISO 8601 formats.
+  # Returns a new Date object with values parsed from `string`, which should
+  # contain an [ISO 8601 formatted
+  # date](rdoc-ref:strftime_formatting.rdoc@ISO+8601+Format+Specifications):
+  #
+  #     d = Date.new(2001, 2, 3)
+  #     s = d.iso8601   # => "2001-02-03"
+  #     Date.iso8601(s) # => #<Date: 2001-02-03>
   #
-  #     Date.iso8601('2001-02-03')        #=> #<Date: 2001-02-03 ...>
-  #     Date.iso8601('20010203')          #=> #<Date: 2001-02-03 ...>
-  #     Date.iso8601('2001-W05-6')        #=> #<Date: 2001-02-03 ...>
+  # See:
   #
-  # Raise an ArgumentError when the string length is longer than *limit*. You can
-  # stop this check by passing `limit: nil`, but note that it may take a long time
-  # to parse.
+  # *   Argument [start](rdoc-ref:date/calendars.rdoc@Argument+start).
+  # *   Argument [limit](rdoc-ref:Date@Argument+limit).
+  #
+  # Related: Date._iso8601 (returns a hash).
   #
   def self.iso8601: (String str, ?Integer start) -> Date
 
   # <!--
   #   rdoc-file=ext/date/date_core.c
-  #   - Date.jd([jd=0[, start=Date::ITALY]])  ->  date
+  #   - Date.jd(jd = 0, start = Date::ITALY) -> date
   # -->
-  # Creates a date object denoting the given chronological Julian day number.
+  # Returns a new Date object formed from the arguments:
+  #
+  #     Date.jd(2451944).to_s # => "2001-02-03"
+  #     Date.jd(2451945).to_s # => "2001-02-04"
+  #     Date.jd(0).to_s       # => "-4712-01-01"
+  #
+  # The returned date is:
+  #
+  # *   Gregorian, if the argument is greater than or equal to `start`:
   #
-  #     Date.jd(2451944)          #=> #<Date: 2001-02-03 ...>
-  #     Date.jd(2451945)          #=> #<Date: 2001-02-04 ...>
-  #     Date.jd(0)                #=> #<Date: -4712-01-01 ...>
+  #         Date::ITALY                         # => 2299161
+  #         Date.jd(Date::ITALY).gregorian?     # => true
+  #         Date.jd(Date::ITALY + 1).gregorian? # => true
   #
-  # See also ::new.
+  # *   Julian, otherwise
+  #
+  #         Date.jd(Date::ITALY - 1).julian?    # => true
+  #
+  # See argument [start](rdoc-ref:date/calendars.rdoc@Argument+start).
+  #
+  # Related: Date.new.
   #
   def self.jd: (Integer jd, ?Integer start) -> Date
 
   # <!--
   #   rdoc-file=ext/date/date_core.c
-  #   - Date.jisx0301(string='-4712-01-01'[, start=Date::ITALY], limit: 128)  ->  date
+  #   - Date.jisx0301(string = '-4712-01-01', start = Date::ITALY, limit: 128) -> date
   # -->
-  # Creates a new Date object by parsing from a string according to some typical
-  # JIS X 0301 formats.
+  # Returns a new Date object with values parsed from `string`, which should be a
+  # valid [JIS X 0301
+  # format](rdoc-ref:strftime_formatting.rdoc@JIS+X+0301+Format):
   #
-  #     Date.jisx0301('H13.02.03')                #=> #<Date: 2001-02-03 ...>
+  #     d = Date.new(2001, 2, 3)
+  #     s = d.jisx0301   # => "H13.02.03"
+  #     Date.jisx0301(s) # => #<Date: 2001-02-03>
   #
   # For no-era year, legacy format, Heisei is assumed.
   #
-  #     Date.jisx0301('13.02.03')                 #=> #<Date: 2001-02-03 ...>
+  #     Date.jisx0301('13.02.03') # => #<Date: 2001-02-03>
+  #
+  # See:
+  #
+  # *   Argument [start](rdoc-ref:date/calendars.rdoc@Argument+start).
+  # *   Argument [limit](rdoc-ref:Date@Argument+limit).
   #
-  # Raise an ArgumentError when the string length is longer than *limit*. You can
-  # stop this check by passing `limit: nil`, but note that it may take a long time
-  # to parse.
+  # Related: Date._jisx0301 (returns a hash).
   #
   def self.jisx0301: (String str, ?Integer start) -> Date
 
   # <!--
   #   rdoc-file=ext/date/date_core.c
-  #   - Date.julian_leap?(year)  ->  bool
+  #   - Date.julian_leap?(year) -> true or false
   # -->
-  # Returns true if the given year is a leap year of the proleptic Julian
-  # calendar.
+  # Returns `true` if the given year is a leap year in the [proleptic Julian
+  # calendar](https://en.wikipedia.org/wiki/Proleptic_Julian_calendar), `false`
+  # otherwise:
   #
-  #     Date.julian_leap?(1900)           #=> true
-  #     Date.julian_leap?(1901)           #=> false
+  #     Date.julian_leap?(1900) # => true
+  #     Date.julian_leap?(1901) # => false
+  #
+  # Related: Date.gregorian_leap?.
   #
   def self.julian_leap?: (Integer year) -> bool
 
   # <!--
   #   rdoc-file=ext/date/date_core.c
-  #   - Date.gregorian_leap?(year)  ->  bool
-  #   - Date.leap?(year)            ->  bool
+  #   - Date.gregorian_leap?(year) -> true or false
   # -->
-  # Returns true if the given year is a leap year of the proleptic Gregorian
-  # calendar.
+  # Returns `true` if the given year is a leap year in the [proleptic Gregorian
+  # calendar](https://en.wikipedia.org/wiki/Proleptic_Gregorian_calendar), `false`
+  # otherwise:
+  #
+  #     Date.gregorian_leap?(2000) # => true
+  #     Date.gregorian_leap?(2001) # => false
   #
-  #     Date.gregorian_leap?(1900)        #=> false
-  #     Date.gregorian_leap?(2000)        #=> true
+  # Related: Date.julian_leap?.
   #
   def self.leap?: (Integer year) -> bool
 
   # <!--
   #   rdoc-file=ext/date/date_core.c
-  #   - Date.ordinal([year=-4712[, yday=1[, start=Date::ITALY]]])  ->  date
+  #   - Date.ordinal(year = -4712, yday = 1, start = Date::ITALY) -> date
   # -->
-  # Creates a date object denoting the given ordinal date.
+  # Returns a new Date object formed fom the arguments.
+  #
+  # With no arguments, returns the date for January 1, -4712:
+  #
+  #     Date.ordinal.to_s # => "-4712-01-01"
+  #
+  # With argument `year`, returns the date for January 1 of that year:
   #
-  # The day of year should be a negative or a positive number (as a relative day
-  # from the end of year when negative).  It should not be zero.
+  #     Date.ordinal(2001).to_s  # => "2001-01-01"
+  #     Date.ordinal(-2001).to_s # => "-2001-01-01"
   #
-  #     Date.ordinal(2001)        #=> #<Date: 2001-01-01 ...>
-  #     Date.ordinal(2001,34)     #=> #<Date: 2001-02-03 ...>
-  #     Date.ordinal(2001,-1)     #=> #<Date: 2001-12-31 ...>
+  # With positive argument `yday` == `n`, returns the date for the `nth` day of
+  # the given year:
   #
-  # See also ::jd and ::new.
+  #     Date.ordinal(2001, 14).to_s # => "2001-01-14"
+  #
+  # With negative argument `yday`, counts backward from the end of the year:
+  #
+  #     Date.ordinal(2001, -14).to_s # => "2001-12-18"
+  #
+  # Raises an exception if `yday` is zero or out of range.
+  #
+  # See argument [start](rdoc-ref:date/calendars.rdoc@Argument+start).
+  #
+  # Related: Date.jd, Date.new.
   #
   def self.ordinal: (?Integer year, ?Integer yday, ?Integer start) -> Date
 
   # <!--
   #   rdoc-file=ext/date/date_core.c
-  #   - Date.parse(string='-4712-01-01'[, comp=true[, start=Date::ITALY]], limit: 128)  ->  date
+  #   - Date.parse(string = '-4712-01-01', comp = true, start = Date::ITALY, limit: 128) -> date
   # -->
-  # Parses the given representation of date and time, and creates a date object.
+  # **Note**: This method recognizes many forms in `string`, but it is not a
+  # validator. For formats, see ["Specialized Format Strings" in Formats for Dates
+  # and Times](rdoc-ref:strftime_formatting.rdoc@Specialized+Format+Strings) If
+  # `string` does not specify a valid date, the result is unpredictable; consider
+  # using Date._strptime instead.
   #
-  # This method *does not* function as a validator.  If the input string does not
-  # match valid formats strictly, you may get a cryptic result.  Should consider
-  # to use `Date.strptime` instead of this method as possible.
+  # Returns a new Date object with values parsed from `string`:
   #
-  # If the optional second argument is true and the detected year is in the range
-  # "00" to "99", considers the year a 2-digit form and makes it full.
+  #     Date.parse('2001-02-03')   # => #<Date: 2001-02-03>
+  #     Date.parse('20010203')     # => #<Date: 2001-02-03>
+  #     Date.parse('3rd Feb 2001') # => #<Date: 2001-02-03>
   #
-  #     Date.parse('2001-02-03')          #=> #<Date: 2001-02-03 ...>
-  #     Date.parse('20010203')            #=> #<Date: 2001-02-03 ...>
-  #     Date.parse('3rd Feb 2001')        #=> #<Date: 2001-02-03 ...>
+  # If `comp` is `true` and the given year is in the range `(0..99)`, the current
+  # century is supplied; otherwise, the year is taken as given:
   #
-  # Raise an ArgumentError when the string length is longer than *limit*. You can
-  # stop this check by passing `limit: nil`, but note that it may take a long time
-  # to parse.
+  #     Date.parse('01-02-03', true)  # => #<Date: 2001-02-03>
+  #     Date.parse('01-02-03', false) # => #<Date: 0001-02-03>
   #
-  def self.parse: (String str, ?boolish complete, ?Integer start) -> Date
+  # See:
+  #
+  # *   Argument [start](rdoc-ref:date/calendars.rdoc@Argument+start).
+  # *   Argument [limit](rdoc-ref:Date@Argument+limit).
+  #
+  # Related: Date._parse (returns a hash).
+  #
+  def self.parse: (?String str, ?boolish complete, ?Integer start) -> Date
 
   # <!--
   #   rdoc-file=ext/date/date_core.c
-  #   - Date.rfc2822(string='Mon, 1 Jan -4712 00:00:00 +0000'[, start=Date::ITALY], limit: 128)  ->  date
-  #   - Date.rfc822(string='Mon, 1 Jan -4712 00:00:00 +0000'[, start=Date::ITALY], limit: 128)   ->  date
+  #   - Date.rfc2822(string = 'Mon, 1 Jan -4712 00:00:00 +0000', start = Date::ITALY, limit: 128) -> date
   # -->
-  # Creates a new Date object by parsing from a string according to some typical
-  # RFC 2822 formats.
+  # Returns a new Date object with values parsed from `string`, which should be a
+  # valid [RFC 2822 date
+  # format](rdoc-ref:strftime_formatting.rdoc@RFC+2822+Format):
+  #
+  #     d = Date.new(2001, 2, 3)
+  #     s = d.rfc2822   # => "Sat, 3 Feb 2001 00:00:00 +0000"
+  #     Date.rfc2822(s) # => #<Date: 2001-02-03>
   #
-  #     Date.rfc2822('Sat, 3 Feb 2001 00:00:00 +0000')
-  #                                               #=> #<Date: 2001-02-03 ...>
+  # See:
   #
-  # Raise an ArgumentError when the string length is longer than *limit*. You can
-  # stop this check by passing `limit: nil`, but note that it may take a long time
-  # to parse.
+  # *   Argument [start](rdoc-ref:date/calendars.rdoc@Argument+start).
+  # *   Argument [limit](rdoc-ref:Date@Argument+limit).
+  #
+  # Related: Date._rfc2822 (returns a hash).
   #
   def self.rfc2822: (String str, ?Integer start) -> Date
 
   # <!--
   #   rdoc-file=ext/date/date_core.c
-  #   - Date.rfc3339(string='-4712-01-01T00:00:00+00:00'[, start=Date::ITALY], limit: 128)  ->  date
+  #   - Date.rfc3339(string = '-4712-01-01T00:00:00+00:00', start = Date::ITALY, limit: 128) -> date
   # -->
-  # Creates a new Date object by parsing from a string according to some typical
-  # RFC 3339 formats.
+  # Returns a new Date object with values parsed from `string`, which should be a
+  # valid [RFC 3339 format](rdoc-ref:strftime_formatting.rdoc@RFC+3339+Format):
+  #
+  #     d = Date.new(2001, 2, 3)
+  #     s = d.rfc3339   # => "2001-02-03T00:00:00+00:00"
+  #     Date.rfc3339(s) # => #<Date: 2001-02-03>
+  #
+  # See:
   #
-  #     Date.rfc3339('2001-02-03T04:05:06+07:00') #=> #<Date: 2001-02-03 ...>
+  # *   Argument [start](rdoc-ref:date/calendars.rdoc@Argument+start).
+  # *   Argument [limit](rdoc-ref:Date@Argument+limit).
   #
-  # Raise an ArgumentError when the string length is longer than *limit*. You can
-  # stop this check by passing `limit: nil`, but note that it may take a long time
-  # to parse.
+  # Related: Date._rfc3339 (returns a hash).
   #
   def self.rfc3339: (String str, ?Integer start) -> Date
 
   # <!--
   #   rdoc-file=ext/date/date_core.c
-  #   - Date.rfc2822(string='Mon, 1 Jan -4712 00:00:00 +0000'[, start=Date::ITALY], limit: 128)  ->  date
-  #   - Date.rfc822(string='Mon, 1 Jan -4712 00:00:00 +0000'[, start=Date::ITALY], limit: 128)   ->  date
+  #   - Date.rfc2822(string = 'Mon, 1 Jan -4712 00:00:00 +0000', start = Date::ITALY, limit: 128) -> date
   # -->
-  # Creates a new Date object by parsing from a string according to some typical
-  # RFC 2822 formats.
+  # Returns a new Date object with values parsed from `string`, which should be a
+  # valid [RFC 2822 date
+  # format](rdoc-ref:strftime_formatting.rdoc@RFC+2822+Format):
+  #
+  #     d = Date.new(2001, 2, 3)
+  #     s = d.rfc2822   # => "Sat, 3 Feb 2001 00:00:00 +0000"
+  #     Date.rfc2822(s) # => #<Date: 2001-02-03>
+  #
+  # See:
   #
-  #     Date.rfc2822('Sat, 3 Feb 2001 00:00:00 +0000')
-  #                                               #=> #<Date: 2001-02-03 ...>
+  # *   Argument [start](rdoc-ref:date/calendars.rdoc@Argument+start).
+  # *   Argument [limit](rdoc-ref:Date@Argument+limit).
   #
-  # Raise an ArgumentError when the string length is longer than *limit*. You can
-  # stop this check by passing `limit: nil`, but note that it may take a long time
-  # to parse.
+  # Related: Date._rfc2822 (returns a hash).
   #
   def self.rfc822: (String str, ?Integer start) -> Date
 
   # <!--
   #   rdoc-file=ext/date/date_core.c
-  #   - Date.strptime([string='-4712-01-01'[, format='%F'[, start=Date::ITALY]]])  ->  date
+  #   - Date.strptime(string = '-4712-01-01', format = '%F', start = Date::ITALY) -> date
   # -->
-  # Parses the given representation of date and time with the given template, and
-  # creates a date object.  strptime does not support specification of flags and
-  # width unlike strftime.
+  # Returns a new Date object with values parsed from `string`, according to the
+  # given `format`:
   #
-  #     Date.strptime('2001-02-03', '%Y-%m-%d')   #=> #<Date: 2001-02-03 ...>
-  #     Date.strptime('03-02-2001', '%d-%m-%Y')   #=> #<Date: 2001-02-03 ...>
-  #     Date.strptime('2001-034', '%Y-%j')        #=> #<Date: 2001-02-03 ...>
-  #     Date.strptime('2001-W05-6', '%G-W%V-%u')  #=> #<Date: 2001-02-03 ...>
-  #     Date.strptime('2001 04 6', '%Y %U %w')    #=> #<Date: 2001-02-03 ...>
-  #     Date.strptime('2001 05 6', '%Y %W %u')    #=> #<Date: 2001-02-03 ...>
-  #     Date.strptime('sat3feb01', '%a%d%b%y')    #=> #<Date: 2001-02-03 ...>
+  #     Date.strptime('2001-02-03', '%Y-%m-%d')  # => #<Date: 2001-02-03>
+  #     Date.strptime('03-02-2001', '%d-%m-%Y')  # => #<Date: 2001-02-03>
+  #     Date.strptime('2001-034', '%Y-%j')       # => #<Date: 2001-02-03>
+  #     Date.strptime('2001-W05-6', '%G-W%V-%u') # => #<Date: 2001-02-03>
+  #     Date.strptime('2001 04 6', '%Y %U %w')   # => #<Date: 2001-02-03>
+  #     Date.strptime('2001 05 6', '%Y %W %u')   # => #<Date: 2001-02-03>
+  #     Date.strptime('sat3feb01', '%a%d%b%y')   # => #<Date: 2001-02-03>
   #
-  # See also strptime(3) and #strftime.
+  # For other formats, see [Formats for Dates and
+  # Times](rdoc-ref:strftime_formatting.rdoc). (Unlike Date.strftime, does not
+  # support flags and width.)
+  #
+  # See argument [start](rdoc-ref:date/calendars.rdoc@Argument+start).
+  #
+  # See also [strptime(3)](https://man7.org/linux/man-pages/man3/strptime.3.html).
+  #
+  # Related: Date._strptime (returns a hash).
   #
   def self.strptime: (String str, ?String format, ?Integer start) -> Date
 
   # <!--
   #   rdoc-file=ext/date/date_core.c
-  #   - Date.today([start=Date::ITALY])  ->  date
+  #   - Date.today(start = Date::ITALY) -> date
   # -->
-  # Creates a date object denoting the present day.
+  # Returns a new Date object constructed from the present date:
   #
-  #     Date.today   #=> #<Date: 2011-06-11 ...>
+  #     Date.today.to_s # => "2022-07-06"
+  #
+  # See argument [start](rdoc-ref:date/calendars.rdoc@Argument+start).
   #
   def self.today: (?Integer start) -> Date
 
   # <!--
   #   rdoc-file=ext/date/date_core.c
-  #   - Date.valid_civil?(year, month, mday[, start=Date::ITALY])  ->  bool
-  #   - Date.valid_date?(year, month, mday[, start=Date::ITALY])   ->  bool
+  #   - Date.valid_civil?(year, month, mday, start = Date::ITALY) -> true or false
   # -->
-  # Returns true if the given calendar date is valid, and false if not. Valid in
-  # this context is whether the arguments passed to this method would be accepted
-  # by ::new.
+  # Returns `true` if the arguments define a valid ordinal date, `false`
+  # otherwise:
+  #
+  #     Date.valid_date?(2001, 2, 3)  # => true
+  #     Date.valid_date?(2001, 2, 29) # => false
+  #     Date.valid_date?(2001, 2, -1) # => true
   #
-  #     Date.valid_date?(2001,2,3)        #=> true
-  #     Date.valid_date?(2001,2,29)       #=> false
-  #     Date.valid_date?(2001,2,-1)       #=> true
+  # See argument [start](rdoc-ref:date/calendars.rdoc@Argument+start).
   #
-  # See also ::jd and ::civil.
+  # Related: Date.jd, Date.new.
   #
   def self.valid_civil?: (Integer year, Integer month, Integer mday, ?Integer start) -> bool
 
   # <!--
   #   rdoc-file=ext/date/date_core.c
-  #   - Date.valid_commercial?(cwyear, cweek, cwday[, start=Date::ITALY])  ->  bool
+  #   - Date.valid_commercial?(cwyear, cweek, cwday, start = Date::ITALY) -> true or false
   # -->
-  # Returns true if the given week date is valid, and false if not.
+  # Returns `true` if the arguments define a valid commercial date, `false`
+  # otherwise:
   #
-  #     Date.valid_commercial?(2001,5,6)  #=> true
-  #     Date.valid_commercial?(2001,5,8)  #=> false
+  #     Date.valid_commercial?(2001, 5, 6) # => true
+  #     Date.valid_commercial?(2001, 5, 8) # => false
   #
-  # See also ::jd and ::commercial.
+  # See Date.commercial.
+  #
+  # See argument [start](rdoc-ref:date/calendars.rdoc@Argument+start).
+  #
+  # Related: Date.jd, Date.commercial.
   #
   def self.valid_commercial?: (Integer cwyear, Integer cweek, Integer cwday, ?Integer start) -> bool
 
   # <!--
   #   rdoc-file=ext/date/date_core.c
-  #   - Date.valid_civil?(year, month, mday[, start=Date::ITALY])  ->  bool
-  #   - Date.valid_date?(year, month, mday[, start=Date::ITALY])   ->  bool
+  #   - Date.valid_civil?(year, month, mday, start = Date::ITALY) -> true or false
   # -->
-  # Returns true if the given calendar date is valid, and false if not. Valid in
-  # this context is whether the arguments passed to this method would be accepted
-  # by ::new.
+  # Returns `true` if the arguments define a valid ordinal date, `false`
+  # otherwise:
+  #
+  #     Date.valid_date?(2001, 2, 3)  # => true
+  #     Date.valid_date?(2001, 2, 29) # => false
+  #     Date.valid_date?(2001, 2, -1) # => true
   #
-  #     Date.valid_date?(2001,2,3)        #=> true
-  #     Date.valid_date?(2001,2,29)       #=> false
-  #     Date.valid_date?(2001,2,-1)       #=> true
+  # See argument [start](rdoc-ref:date/calendars.rdoc@Argument+start).
   #
-  # See also ::jd and ::civil.
+  # Related: Date.jd, Date.new.
   #
   def self.valid_date?: (Integer year, Integer month, Integer mday, ?Integer start) -> bool
 
   # <!--
   #   rdoc-file=ext/date/date_core.c
-  #   - Date.valid_jd?(jd[, start=Date::ITALY])  ->  bool
+  #   - Date.valid_jd?(jd, start = Date::ITALY) -> true
   # -->
-  # Just returns true.  It's nonsense, but is for symmetry.
+  # Implemented for compatibility; returns `true` unless `jd` is invalid (i.e.,
+  # not a Numeric).
   #
-  #     Date.valid_jd?(2451944)           #=> true
+  #     Date.valid_jd?(2451944) # => true
   #
-  # See also ::jd.
+  # See argument [start](rdoc-ref:date/calendars.rdoc@Argument+start).
+  #
+  # Related: Date.jd.
   #
   def self.valid_jd?: (Integer jd, ?Integer start) -> bool
 
   # <!--
   #   rdoc-file=ext/date/date_core.c
-  #   - Date.valid_ordinal?(year, yday[, start=Date::ITALY])  ->  bool
+  #   - Date.valid_ordinal?(year, yday, start = Date::ITALY) -> true or false
   # -->
-  # Returns true if the given ordinal date is valid, and false if not.
+  # Returns `true` if the arguments define a valid ordinal date, `false`
+  # otherwise:
+  #
+  #     Date.valid_ordinal?(2001, 34)  # => true
+  #     Date.valid_ordinal?(2001, 366) # => false
   #
-  #     Date.valid_ordinal?(2001,34)      #=> true
-  #     Date.valid_ordinal?(2001,366)     #=> false
+  # See argument [start](rdoc-ref:date/calendars.rdoc@Argument+start).
   #
-  # See also ::jd and ::ordinal.
+  # Related: Date.jd, Date.ordinal.
   #
   def self.valid_ordinal?: (Integer year, Integer yday, ?Integer start) -> bool
 
   # <!--
   #   rdoc-file=ext/date/date_core.c
-  #   - Date.xmlschema(string='-4712-01-01'[, start=Date::ITALY], limit: 128)  ->  date
+  #   - Date.xmlschema(string = '-4712-01-01', start = Date::ITALY, limit: 128)  ->  date
   # -->
-  # Creates a new Date object by parsing from a string according to some typical
-  # XML Schema formats.
+  # Returns a new Date object with values parsed from `string`, which should be a
+  # valid XML date format:
   #
-  #     Date.xmlschema('2001-02-03')      #=> #<Date: 2001-02-03 ...>
+  #     d = Date.new(2001, 2, 3)
+  #     s = d.xmlschema   # => "2001-02-03"
+  #     Date.xmlschema(s) # => #<Date: 2001-02-03>
   #
-  # Raise an ArgumentError when the string length is longer than *limit*. You can
-  # stop this check by passing `limit: nil`, but note that it may take a long time
-  # to parse.
+  # See:
+  #
+  # *   Argument [start](rdoc-ref:date/calendars.rdoc@Argument+start).
+  # *   Argument [limit](rdoc-ref:Date@Argument+limit).
+  #
+  # Related: Date._xmlschema (returns a hash).
   #
   def self.xmlschema: (String str, ?Integer start) -> Date
 
-  public
-
   # <!--
   #   rdoc-file=ext/date/date_core.c
   #   - d + other  ->  date
@@ -647,10 +743,10 @@ class Date
   #   rdoc-file=ext/date/date_core.c
   #   - d - other  ->  date or rational
   # -->
-  # Returns the difference between the two dates if the other is a date object.
-  # If the other is a numeric value, returns a date object pointing `other` days
-  # before self.  If the other is a fractional number, assumes its precision is at
-  # most nanosecond.
+  # If the other is a date object, returns a Rational whose value is the
+  # difference between the two dates in days. If the other is a numeric value,
+  # returns a date object pointing `other` days before self. If the other is a
+  # fractional number, assumes its precision is at most nanosecond.
   #
   #     Date.new(2001,2,3) - 1   #=> #<Date: 2001-02-02 ...>
   #     DateTime.new(2001,2,3) - Rational(1,2)
@@ -667,85 +763,133 @@ class Date
   #   rdoc-file=ext/date/date_core.c
   #   - d << n  ->  date
   # -->
-  # Returns a date object pointing `n` months before self. The argument `n` should
-  # be a numeric value.
+  # Returns a new Date object representing the date `n` months earlier; `n` should
+  # be a numeric:
   #
-  #     Date.new(2001,2,3)  <<  1   #=> #<Date: 2001-01-03 ...>
-  #     Date.new(2001,2,3)  << -2   #=> #<Date: 2001-04-03 ...>
+  #     (Date.new(2001, 2, 3) << 1).to_s  # => "2001-01-03"
+  #     (Date.new(2001, 2, 3) << -2).to_s # => "2001-04-03"
   #
-  # When the same day does not exist for the corresponding month, the last day of
-  # the month is used instead:
+  # When the same day does not exist for the new month, the last day of that month
+  # is used instead:
   #
-  #     Date.new(2001,3,28) << 1   #=> #<Date: 2001-02-28 ...>
-  #     Date.new(2001,3,31) << 1   #=> #<Date: 2001-02-28 ...>
+  #     (Date.new(2001, 3, 31) << 1).to_s  # => "2001-02-28"
+  #     (Date.new(2001, 3, 31) << -6).to_s # => "2001-09-30"
   #
-  # This also results in the following, possibly unexpected, behavior:
+  # This results in the following, possibly unexpected, behaviors:
   #
-  #     Date.new(2001,3,31) << 2         #=> #<Date: 2001-01-31 ...>
-  #     Date.new(2001,3,31) << 1 << 1    #=> #<Date: 2001-01-28 ...>
+  #     d0 = Date.new(2001, 3, 31)
+  #     d0 << 2      # => #<Date: 2001-01-31>
+  #     d0 << 1 << 1 # => #<Date: 2001-01-28>
   #
-  #     Date.new(2001,3,31) << 1 << -1   #=> #<Date: 2001-03-28 ...>
+  #     d0 = Date.new(2001, 3, 31)
+  #     d1 = d0 << 1  # => #<Date: 2001-02-28>
+  #     d2 = d1 << -1 # => #<Date: 2001-03-28>
   #
   def <<: (Integer month) -> Date
 
   # <!--
   #   rdoc-file=ext/date/date_core.c
-  #   - d <=> other  -> -1, 0, +1 or nil
+  #   - self <=> other  -> -1, 0, 1 or nil
   # -->
-  # Compares the two dates and returns -1, zero, 1 or nil.  The other should be a
-  # date object or a numeric value as an astronomical Julian day number.
+  # Compares `self` and `other`, returning:
+  #
+  # *   `-1` if `other` is larger.
+  # *   `0` if the two are equal.
+  # *   `1` if `other` is smaller.
+  # *   `nil` if the two are incomparable.
+  #
+  # Argument `other` may be:
   #
-  #     Date.new(2001,2,3) <=> Date.new(2001,2,4)   #=> -1
-  #     Date.new(2001,2,3) <=> Date.new(2001,2,3)   #=> 0
-  #     Date.new(2001,2,3) <=> Date.new(2001,2,2)   #=> 1
-  #     Date.new(2001,2,3) <=> Object.new           #=> nil
-  #     Date.new(2001,2,3) <=> Rational(4903887,2)  #=> 0
+  # *   Another Date object:
   #
-  # See also Comparable.
+  #         d = Date.new(2022, 7, 27) # => #<Date: 2022-07-27 ((2459788j,0s,0n),+0s,2299161j)>
+  #         prev_date = d.prev_day    # => #<Date: 2022-07-26 ((2459787j,0s,0n),+0s,2299161j)>
+  #         next_date = d.next_day    # => #<Date: 2022-07-28 ((2459789j,0s,0n),+0s,2299161j)>
+  #         d <=> next_date           # => -1
+  #         d <=> d                   # => 0
+  #         d <=> prev_date           # => 1
+  #
+  # *   A DateTime object:
+  #
+  #         d <=> DateTime.new(2022, 7, 26) # => 1
+  #         d <=> DateTime.new(2022, 7, 27) # => 0
+  #         d <=> DateTime.new(2022, 7, 28) # => -1
+  #
+  # *   A numeric (compares `self.ajd` to `other`):
+  #
+  #         d <=> 2459788 # => -1
+  #         d <=> 2459787 # => 1
+  #         d <=> 2459786 # => 1
+  #         d <=> d.ajd   # => 0
+  #
+  # *   Any other object:
+  #
+  #         d <=> Object.new # => nil
   #
   def <=>: (untyped other) -> Integer?
 
   # <!--
   #   rdoc-file=ext/date/date_core.c
-  #   - d === other  ->  bool
+  #   - self === other -> true, false, or nil.
   # -->
-  # Returns true if they are the same day.
+  # Returns `true` if `self` and `other` represent the same date, `false` if not,
+  # `nil` if the two are not comparable.
+  #
+  # Argument `other` may be:
+  #
+  # *   Another Date object:
+  #
+  #         d = Date.new(2022, 7, 27) # => #<Date: 2022-07-27 ((2459788j,0s,0n),+0s,2299161j)>
+  #         prev_date = d.prev_day    # => #<Date: 2022-07-26 ((2459787j,0s,0n),+0s,2299161j)>
+  #         next_date = d.next_day    # => #<Date: 2022-07-28 ((2459789j,0s,0n),+0s,2299161j)>
+  #         d === prev_date           # => false
+  #         d === d                   # => true
+  #         d === next_date           # => false
+  #
+  # *   A DateTime object:
   #
-  #     Date.new(2001,2,3) === Date.new(2001,2,3)
-  #                                       #=> true
-  #     Date.new(2001,2,3) === Date.new(2001,2,4)
-  #                                       #=> false
-  #     DateTime.new(2001,2,3) === DateTime.new(2001,2,3,12)
-  #                                       #=> true
-  #     DateTime.new(2001,2,3) === DateTime.new(2001,2,3,0,0,0,'+24:00')
-  #                                       #=> true
-  #     DateTime.new(2001,2,3) === DateTime.new(2001,2,4,0,0,0,'+24:00')
-  #                                       #=> false
+  #         d === DateTime.new(2022, 7, 26) # => false
+  #         d === DateTime.new(2022, 7, 27) # => true
+  #         d === DateTime.new(2022, 7, 28) # => false
+  #
+  # *   A numeric (compares `self.jd` to `other`):
+  #
+  #         d === 2459788 # => true
+  #         d === 2459787 # => false
+  #         d === 2459786 # => false
+  #         d === d.jd    # => true
+  #
+  # *   An object not comparable:
+  #
+  #         d === Object.new # => nil
   #
   def ===: (Date other) -> bool
 
   # <!--
   #   rdoc-file=ext/date/date_core.c
-  #   - d >> n  ->  date
+  #   - d >> n -> new_date
   # -->
-  # Returns a date object pointing `n` months after self. The argument `n` should
-  # be a numeric value.
+  # Returns a new Date object representing the date `n` months later; `n` should
+  # be a numeric:
   #
-  #     Date.new(2001,2,3)  >>  1   #=> #<Date: 2001-03-03 ...>
-  #     Date.new(2001,2,3)  >> -2   #=> #<Date: 2000-12-03 ...>
+  #     (Date.new(2001, 2, 3) >> 1).to_s  # => "2001-03-03"
+  #     (Date.new(2001, 2, 3) >> -2).to_s # => "2000-12-03"
   #
-  # When the same day does not exist for the corresponding month, the last day of
-  # the month is used instead:
+  # When the same day does not exist for the new month, the last day of that month
+  # is used instead:
   #
-  #     Date.new(2001,1,28) >> 1   #=> #<Date: 2001-02-28 ...>
-  #     Date.new(2001,1,31) >> 1   #=> #<Date: 2001-02-28 ...>
+  #     (Date.new(2001, 1, 31) >> 1).to_s  # => "2001-02-28"
+  #     (Date.new(2001, 1, 31) >> -4).to_s # => "2000-09-30"
   #
-  # This also results in the following, possibly unexpected, behavior:
+  # This results in the following, possibly unexpected, behaviors:
   #
-  #     Date.new(2001,1,31) >> 2         #=> #<Date: 2001-03-31 ...>
-  #     Date.new(2001,1,31) >> 1 >> 1    #=> #<Date: 2001-03-28 ...>
+  #     d0 = Date.new(2001, 1, 31)
+  #     d1 = d0 >> 1 # => #<Date: 2001-02-28>
+  #     d2 = d1 >> 1 # => #<Date: 2001-03-28>
   #
-  #     Date.new(2001,1,31) >> 1 >> -1   #=> #<Date: 2001-01-28 ...>
+  #     d0 = Date.new(2001, 1, 31)
+  #     d1 = d0 >> 1  # => #<Date: 2001-02-28>
+  #     d2 = d1 >> -1 # => #<Date: 2001-01-28>
   #
   def >>: (Integer month) -> Date
 
@@ -775,143 +919,186 @@ class Date
 
   # <!--
   #   rdoc-file=ext/date/date_core.c
-  #   - d.asctime  ->  string
-  #   - d.ctime    ->  string
+  #   - asctime -> string
   # -->
-  # Returns a string in asctime(3) format (but without "n\0" at the end).  This
-  # method is equivalent to strftime('%c').
+  # Equivalent to #strftime with argument `'%a %b %e %T %Y'` (or its [shorthand
+  # form](rdoc-ref:strftime_formatting.rdoc@Shorthand+Conversion+Specifiers)
+  # `'%c'`):
+  #
+  #     Date.new(2001, 2, 3).asctime # => "Sat Feb  3 00:00:00 2001"
   #
-  # See also asctime(3) or ctime(3).
+  # See [asctime](https://linux.die.net/man/3/asctime).
   #
   def asctime: () -> String
 
   # <!-- rdoc-file=ext/date/date_core.c -->
-  # Returns a string in asctime(3) format (but without "n\0" at the end).  This
-  # method is equivalent to strftime('%c').
+  # Equivalent to #strftime with argument `'%a %b %e %T %Y'` (or its [shorthand
+  # form](rdoc-ref:strftime_formatting.rdoc@Shorthand+Conversion+Specifiers)
+  # `'%c'`):
   #
-  # See also asctime(3) or ctime(3).
+  #     Date.new(2001, 2, 3).asctime # => "Sat Feb  3 00:00:00 2001"
+  #
+  # See [asctime](https://linux.die.net/man/3/asctime).
   #
   def ctime: () -> String
 
   # <!--
   #   rdoc-file=ext/date/date_core.c
-  #   - d.cwday  ->  fixnum
+  #   - cwday -> integer
   # -->
-  # Returns the day of calendar week (1-7, Monday is 1).
+  # Returns the commercial-date weekday index for `self` (see Date.commercial); 1
+  # is Monday:
   #
-  #     Date.new(2001,2,3).cwday          #=> 6
+  #     Date.new(2001, 2, 3).cwday # => 6
   #
   def cwday: () -> Integer
 
   # <!--
   #   rdoc-file=ext/date/date_core.c
-  #   - d.cweek  ->  fixnum
+  #   - cweek -> integer
   # -->
-  # Returns the calendar week number (1-53).
+  # Returns commercial-date week index for `self` (see Date.commercial):
   #
-  #     Date.new(2001,2,3).cweek          #=> 5
+  #     Date.new(2001, 2, 3).cweek # => 5
   #
   def cweek: () -> Integer
 
   # <!--
   #   rdoc-file=ext/date/date_core.c
-  #   - d.cwyear  ->  integer
+  #   - cwyear -> integer
   # -->
-  # Returns the calendar week based year.
+  # Returns commercial-date year for `self` (see Date.commercial):
   #
-  #     Date.new(2001,2,3).cwyear         #=> 2001
-  #     Date.new(2000,1,1).cwyear         #=> 1999
+  #     Date.new(2001, 2, 3).cwyear # => 2001
+  #     Date.new(2000, 1, 1).cwyear # => 1999
   #
   def cwyear: () -> Integer
 
   # <!-- rdoc-file=ext/date/date_core.c -->
-  # Returns the day of the month (1-31).
+  # Returns the day of the month in range (1..31):
   #
-  #     Date.new(2001,2,3).mday           #=> 3
+  #     Date.new(2001, 2, 3).mday # => 3
   #
   def day: () -> Integer
 
   # <!--
   #   rdoc-file=ext/date/date_core.c
-  #   - d.downto(min)              ->  enumerator
-  #   - d.downto(min){|date| ...}  ->  self
+  #   - deconstruct_keys(array_of_names_or_nil) -> hash
   # -->
-  # This method is equivalent to step(min, -1){|date| ...}.
+  # Returns a hash of the name/value pairs, to use in pattern matching. Possible
+  # keys are: `:year`, `:month`, `:day`, `:wday`, `:yday`.
+  #
+  # Possible usages:
+  #
+  #     d = Date.new(2022, 10, 5)
+  #
+  #     if d in wday: 3, day: ..7  # uses deconstruct_keys underneath
+  #       puts "first Wednesday of the month"
+  #     end
+  #     #=> prints "first Wednesday of the month"
+  #
+  #     case d
+  #     in year: ...2022
+  #       puts "too old"
+  #     in month: ..9
+  #       puts "quarter 1-3"
+  #     in wday: 1..5, month:
+  #       puts "working day in month #{month}"
+  #     end
+  #     #=> prints "working day in month 10"
+  #
+  # Note that deconstruction by pattern can also be combined with class check:
+  #
+  #     if d in Date(wday: 3, day: ..7)
+  #       puts "first Wednesday of the month"
+  #     end
+  #
+  def deconstruct_keys: (Array[Symbol]?) -> Hash[Symbol, Integer]
+
+  # <!--
+  #   rdoc-file=ext/date/date_core.c
+  #   - downto(min){|date| ... } -> self
+  # -->
+  # Equivalent to #step with arguments `min` and `-1`.
   #
   def downto: (Date min) { (Date) -> untyped } -> Date
             | (Date min) -> Enumerator[Date, Date]
 
   # <!--
   #   rdoc-file=ext/date/date_core.c
-  #   - d.england  ->  date
+  #   - england -> new_date
   # -->
-  # This method is equivalent to new_start(Date::ENGLAND).
+  # Equivalent to Date#new_start with argument Date::ENGLAND.
   #
   def england: () -> Date
 
   # <!--
   #   rdoc-file=ext/date/date_core.c
-  #   - d.friday?  ->  bool
+  #   - friday? -> true or false
   # -->
-  # Returns true if the date is Friday.
+  # Returns `true` if `self` is a Friday, `false` otherwise.
   #
   def friday?: () -> bool
 
   # <!--
   #   rdoc-file=ext/date/date_core.c
-  #   - d.gregorian  ->  date
+  #   - gregorian -> new_date
   # -->
-  # This method is equivalent to new_start(Date::GREGORIAN).
+  # Equivalent to Date#new_start with argument Date::GREGORIAN.
   #
   def gregorian: () -> Date
 
   # <!--
   #   rdoc-file=ext/date/date_core.c
-  #   - d.gregorian?  ->  bool
+  #   - gregorian? -> true or false
   # -->
-  # Returns true if the date is on or after the day of calendar reform.
+  # Returns `true` if the date is on or after the date of calendar reform, `false`
+  # otherwise:
   #
-  #     Date.new(1582,10,15).gregorian?          #=> true
-  #     (Date.new(1582,10,15) - 1).gregorian?    #=> false
+  #     Date.new(1582, 10, 15).gregorian?       # => true
+  #     (Date.new(1582, 10, 15) - 1).gregorian? # => false
   #
   def gregorian?: () -> bool
 
   # <!--
   #   rdoc-file=ext/date/date_core.c
-  #   - d.httpdate  ->  string
+  #   - httpdate -> string
   # -->
-  # This method is equivalent to strftime('%a, %d %b %Y %T GMT'). See also RFC
-  # 2616.
+  # Equivalent to #strftime with argument `'%a, %d %b %Y %T GMT'`; see [Formats
+  # for Dates and Times](rdoc-ref:strftime_formatting.rdoc):
+  #
+  #     Date.new(2001, 2, 3).httpdate # => "Sat, 03 Feb 2001 00:00:00 GMT"
   #
   def httpdate: () -> String
 
   # <!--
   #   rdoc-file=ext/date/date_core.c
-  #   - d.inspect  ->  string
+  #   - inspect -> string
   # -->
-  # Returns the value as a string for inspection.
+  # Returns a string representation of `self`:
   #
-  #     Date.new(2001,2,3).inspect
-  #               #=> "#<Date: 2001-02-03>"
-  #     DateTime.new(2001,2,3,4,5,6,'-7').inspect
-  #               #=> "#<DateTime: 2001-02-03T04:05:06-07:00>"
+  #     Date.new(2001, 2, 3).inspect
+  #     # => "#<Date: 2001-02-03 ((2451944j,0s,0n),+0s,2299161j)>"
   #
   def inspect: () -> String
 
   # <!--
   #   rdoc-file=ext/date/date_core.c
-  #   - d.iso8601    ->  string
-  #   - d.xmlschema  ->  string
+  #   - iso8601    ->  string
   # -->
-  # This method is equivalent to strftime('%F').
+  # Equivalent to #strftime with argument `'%Y-%m-%d'` (or its [shorthand
+  # form](rdoc-ref:strftime_formatting.rdoc@Shorthand+Conversion+Specifiers)
+  # `'%F'`);
+  #
+  #     Date.new(2001, 2, 3).iso8601 # => "2001-02-03"
   #
   def iso8601: () -> String
 
   # <!--
   #   rdoc-file=ext/date/date_core.c
-  #   - d.italy  ->  date
+  #   - italy -> new_date
   # -->
-  # This method is equivalent to new_start(Date::ITALY).
+  # Equivalent to Date#new_start with argument Date::ITALY.
   #
   def italy: () -> Date
 
@@ -929,63 +1116,64 @@ class Date
 
   # <!--
   #   rdoc-file=ext/date/date_core.c
-  #   - d.jisx0301  ->  string
+  #   - jisx0301 -> string
   # -->
-  # Returns a string in a JIS X 0301 format.
+  # Returns a string representation of the date in `self` in JIS X 0301 format.
   #
-  #     Date.new(2001,2,3).jisx0301       #=> "H13.02.03"
+  #     Date.new(2001, 2, 3).jisx0301 # => "H13.02.03"
   #
   def jisx0301: () -> String
 
   # <!--
   #   rdoc-file=ext/date/date_core.c
-  #   - d.julian  ->  date
+  #   - julian -> new_date
   # -->
-  # This method is equivalent to new_start(Date::JULIAN).
+  # Equivalent to Date#new_start with argument Date::JULIAN.
   #
   def julian: () -> Date
 
   # <!--
   #   rdoc-file=ext/date/date_core.c
-  #   - d.julian?  ->  bool
+  #   - d.julian? -> true or false
   # -->
-  # Returns true if the date is before the day of calendar reform.
+  # Returns `true` if the date is before the date of calendar reform, `false`
+  # otherwise:
   #
-  #     Date.new(1582,10,15).julian?             #=> false
-  #     (Date.new(1582,10,15) - 1).julian?       #=> true
+  #     (Date.new(1582, 10, 15) - 1).julian? # => true
+  #     Date.new(1582, 10, 15).julian?       # => false
   #
   def julian?: () -> bool
 
   # <!--
   #   rdoc-file=ext/date/date_core.c
-  #   - d.ld  ->  integer
+  #   - ld -> integer
   # -->
-  # Returns the Lilian day number.  This is a whole number, which is adjusted by
-  # the offset as the local time.
+  # Returns the [Lilian day number](https://en.wikipedia.org/wiki/Lilian_date),
+  # which is the number of days since the beginning of the Gregorian calendar,
+  # October 15, 1582.
   #
-  #     Date.new(2001,2,3).ld            #=> 152784
+  #     Date.new(2001, 2, 3).ld # => 152784
   #
   def ld: () -> Integer
 
   # <!--
   #   rdoc-file=ext/date/date_core.c
-  #   - d.leap?  ->  bool
+  #   - leap? -> true or false
   # -->
-  # Returns true if the year is a leap year.
+  # Returns `true` if the year is a leap year, `false` otherwise:
   #
-  #     Date.new(2000).leap?      #=> true
-  #     Date.new(2001).leap?      #=> false
+  #     Date.new(2000).leap? # => true
+  #     Date.new(2001).leap? # => false
   #
   def leap?: () -> bool
 
   # <!--
   #   rdoc-file=ext/date/date_core.c
-  #   - d.mday  ->  fixnum
-  #   - d.day   ->  fixnum
+  #   - mday -> integer
   # -->
-  # Returns the day of the month (1-31).
+  # Returns the day of the month in range (1..31):
   #
-  #     Date.new(2001,2,3).mday           #=> 3
+  #     Date.new(2001, 2, 3).mday # => 3
   #
   def mday: () -> Integer
 
@@ -1003,376 +1191,250 @@ class Date
 
   # <!--
   #   rdoc-file=ext/date/date_core.c
-  #   - d.mon    ->  fixnum
-  #   - d.month  ->  fixnum
+  #   - mon -> integer
   # -->
-  # Returns the month (1-12).
+  # Returns the month in range (1..12):
   #
-  #     Date.new(2001,2,3).mon            #=> 2
+  #     Date.new(2001, 2, 3).mon # => 2
   #
   def mon: () -> Integer
 
   # <!--
   #   rdoc-file=ext/date/date_core.c
-  #   - d.monday?  ->  bool
+  #   - monday? -> true or false
   # -->
-  # Returns true if the date is Monday.
+  # Returns `true` if `self` is a Monday, `false` otherwise.
   #
   def monday?: () -> bool
 
   # <!-- rdoc-file=ext/date/date_core.c -->
-  # Returns the month (1-12).
+  # Returns the month in range (1..12):
   #
-  #     Date.new(2001,2,3).mon            #=> 2
+  #     Date.new(2001, 2, 3).mon # => 2
   #
   def month: () -> Integer
 
   # <!--
   #   rdoc-file=ext/date/date_core.c
-  #   - d.new_start([start=Date::ITALY])  ->  date
+  #   - new_start(start = Date::ITALY]) -> new_date
   # -->
-  # Duplicates self and resets its day of calendar reform.
+  # Returns a copy of `self` with the given `start` value:
+  #
+  #     d0 = Date.new(2000, 2, 3)
+  #     d0.julian? # => false
+  #     d1 = d0.new_start(Date::JULIAN)
+  #     d1.julian? # => true
   #
-  #     d = Date.new(1582,10,15)
-  #     d.new_start(Date::JULIAN)         #=> #<Date: 1582-10-05 ...>
+  # See argument [start](rdoc-ref:date/calendars.rdoc@Argument+start).
   #
   def new_start: (?Integer start) -> Date
 
   # <!--
   #   rdoc-file=ext/date/date_core.c
-  #   - d.succ  ->  date
-  #   - d.next  ->  date
+  #   - d.next -> new_date
   # -->
-  # Returns a date object denoting the following day.
+  # Returns a new Date object representing the following day:
+  #
+  #     d = Date.new(2001, 2, 3)
+  #     d.to_s      # => "2001-02-03"
+  #     d.next.to_s # => "2001-02-04"
   #
   def next: () -> Date
 
   # <!--
   #   rdoc-file=ext/date/date_core.c
-  #   - d.next_day([n=1])  ->  date
+  #   - next_day(n = 1) -> new_date
   # -->
-  # This method is equivalent to d + n.
+  # Equivalent to Date#+ with argument `n`.
   #
   def next_day: (?Integer day) -> Date
 
   # <!--
   #   rdoc-file=ext/date/date_core.c
-  #   - d.next_month([n=1])  ->  date
+  #   - next_month(n = 1) -> new_date
   # -->
-  # This method is equivalent to d >> n.
-  #
-  # See Date#>> for examples.
+  # Equivalent to #>> with argument `n`.
   #
   def next_month: (?Integer month) -> Date
 
   # <!--
   #   rdoc-file=ext/date/date_core.c
-  #   - d.next_year([n=1])  ->  date
+  #   - next_year(n = 1) -> new_date
   # -->
-  # This method is equivalent to d >> (n * 12).
-  #
-  #     Date.new(2001,2,3).next_year      #=> #<Date: 2002-02-03 ...>
-  #     Date.new(2008,2,29).next_year     #=> #<Date: 2009-02-28 ...>
-  #     Date.new(2008,2,29).next_year(4)  #=> #<Date: 2012-02-29 ...>
-  #
-  # See also Date#>>.
+  # Equivalent to #>> with argument `n * 12`.
   #
   def next_year: (?Integer year) -> Date
 
   # <!--
   #   rdoc-file=ext/date/date_core.c
-  #   - d.prev_day([n=1])  ->  date
+  #   - prev_day(n = 1) -> new_date
   # -->
-  # This method is equivalent to d - n.
+  # Equivalent to Date#- with argument `n`.
   #
   def prev_day: (?Integer day) -> Date
 
   # <!--
   #   rdoc-file=ext/date/date_core.c
-  #   - d.prev_month([n=1])  ->  date
+  #   - prev_month(n = 1) -> new_date
   # -->
-  # This method is equivalent to d << n.
-  #
-  # See Date#<< for examples.
+  # Equivalent to #<< with argument `n`.
   #
   def prev_month: (?Integer month) -> Date
 
   # <!--
   #   rdoc-file=ext/date/date_core.c
-  #   - d.prev_year([n=1])  ->  date
+  #   - prev_year(n = 1) -> new_date
   # -->
-  # This method is equivalent to d << (n * 12).
-  #
-  #     Date.new(2001,2,3).prev_year      #=> #<Date: 2000-02-03 ...>
-  #     Date.new(2008,2,29).prev_year     #=> #<Date: 2007-02-28 ...>
-  #     Date.new(2008,2,29).prev_year(4)  #=> #<Date: 2004-02-29 ...>
-  #
-  # See also Date#<<.
+  # Equivalent to #<< with argument `n * 12`.
   #
   def prev_year: (?Integer year) -> Date
 
   # <!--
   #   rdoc-file=ext/date/date_core.c
-  #   - d.rfc2822  ->  string
-  #   - d.rfc822   ->  string
+  #   - rfc2822 -> string
   # -->
-  # This method is equivalent to strftime('%a, %-d %b %Y %T %z').
+  # Equivalent to #strftime with argument `'%a, %-d %b %Y %T %z'`; see [Formats
+  # for Dates and Times](rdoc-ref:strftime_formatting.rdoc):
+  #
+  #     Date.new(2001, 2, 3).rfc2822 # => "Sat, 3 Feb 2001 00:00:00 +0000"
   #
   def rfc2822: () -> String
 
   # <!--
   #   rdoc-file=ext/date/date_core.c
-  #   - d.rfc3339  ->  string
+  #   - rfc3339 -> string
   # -->
-  # This method is equivalent to strftime('%FT%T%:z').
+  # Equivalent to #strftime with argument `'%FT%T%:z'`; see [Formats for Dates and
+  # Times](rdoc-ref:strftime_formatting.rdoc):
+  #
+  #     Date.new(2001, 2, 3).rfc3339 # => "2001-02-03T00:00:00+00:00"
   #
   def rfc3339: () -> String
 
   # <!-- rdoc-file=ext/date/date_core.c -->
-  # Creates a new Date object by parsing from a string according to some typical
-  # RFC 2822 formats.
+  # Returns a new Date object with values parsed from `string`, which should be a
+  # valid [RFC 2822 date
+  # format](rdoc-ref:strftime_formatting.rdoc@RFC+2822+Format):
+  #
+  #     d = Date.new(2001, 2, 3)
+  #     s = d.rfc2822   # => "Sat, 3 Feb 2001 00:00:00 +0000"
+  #     Date.rfc2822(s) # => #<Date: 2001-02-03>
   #
-  #     Date.rfc2822('Sat, 3 Feb 2001 00:00:00 +0000')
-  #                                               #=> #<Date: 2001-02-03 ...>
+  # See:
   #
-  # Raise an ArgumentError when the string length is longer than *limit*. You can
-  # stop this check by passing `limit: nil`, but note that it may take a long time
-  # to parse.
+  # *   Argument [start](rdoc-ref:date/calendars.rdoc@Argument+start).
+  # *   Argument [limit](rdoc-ref:Date@Argument+limit).
+  #
+  # Related: Date._rfc2822 (returns a hash).
   #
   def rfc822: () -> String
 
   # <!--
   #   rdoc-file=ext/date/date_core.c
-  #   - d.saturday?  ->  bool
+  #   - saturday? -> true or false
   # -->
-  # Returns true if the date is Saturday.
+  # Returns `true` if `self` is a Saturday, `false` otherwise.
   #
   def saturday?: () -> bool
 
   # <!--
   #   rdoc-file=ext/date/date_core.c
-  #   - d.start  ->  float
+  #   - start -> float
   # -->
-  # Returns the Julian day number denoting the day of calendar reform.
+  # Returns the Julian start date for calendar reform; if not an infinity, the
+  # returned value is suitable for passing to Date#jd:
+  #
+  #     d = Date.new(2001, 2, 3, Date::ITALY)
+  #     s = d.start     # => 2299161.0
+  #     Date.jd(s).to_s # => "1582-10-15"
   #
-  #     Date.new(2001,2,3).start                  #=> 2299161.0
-  #     Date.new(2001,2,3,Date::GREGORIAN).start  #=> -Infinity
+  #     d = Date.new(2001, 2, 3, Date::ENGLAND)
+  #     s = d.start     # => 2361222.0
+  #     Date.jd(s).to_s # => "1752-09-14"
+  #
+  #     Date.new(2001, 2, 3, Date::GREGORIAN).start # => -Infinity
+  #     Date.new(2001, 2, 3, Date::JULIAN).start    # => Infinity
+  #
+  # See argument [start](rdoc-ref:date/calendars.rdoc@Argument+start).
   #
   def start: () -> Float
 
   # <!--
   #   rdoc-file=ext/date/date_core.c
-  #   - d.step(limit[, step=1])              ->  enumerator
-  #   - d.step(limit[, step=1]){|date| ...}  ->  self
+  #   - step(limit, step = 1){|date| ... } -> self
   # -->
-  # Iterates evaluation of the given block, which takes a date object. The limit
-  # should be a date object.
+  # Calls the block with specified dates; returns `self`.
+  #
+  # *   The first `date` is `self`.
+  # *   Each successive `date` is `date + step`, where `step` is the numeric step
+  #     size in days.
+  # *   The last date is the last one that is before or equal to `limit`, which
+  #     should be a Date object.
+  #
+  # Example:
+  #
+  #     limit = Date.new(2001, 12, 31)
+  #     Date.new(2001).step(limit){|date| p date.to_s if date.mday == 31 }
   #
-  #     Date.new(2001).step(Date.new(2001,-1,-1)).select{|d| d.sunday?}.size
-  #                               #=> 52
+  # Output:
+  #
+  #     "2001-01-31"
+  #     "2001-03-31"
+  #     "2001-05-31"
+  #     "2001-07-31"
+  #     "2001-08-31"
+  #     "2001-10-31"
+  #     "2001-12-31"
+  #
+  # Returns an Enumerator if no block is given.
   #
   def step: (Date limit, ?Integer step) { (Date) -> untyped } -> Date
           | (Date limit, ?Integer step) -> ::Enumerator[Date, Date]
 
   # <!--
   #   rdoc-file=ext/date/date_core.c
-  #   - d.strftime([format='%F'])  ->  string
-  # -->
-  # Formats date according to the directives in the given format string. The
-  # directives begin with a percent (%) character. Any text not listed as a
-  # directive will be passed through to the output string.
-  #
-  # A directive consists of a percent (%) character, zero or more flags, an
-  # optional minimum field width, an optional modifier, and a conversion specifier
-  # as follows.
-  #
-  #     %<flags><width><modifier><conversion>
-  #
-  # Flags:
-  #     -  don't pad a numerical output.
-  #     _  use spaces for padding.
-  #     0  use zeros for padding.
-  #     ^  upcase the result string.
-  #     #  change case.
-  #
-  # The minimum field width specifies the minimum width.
-  #
-  # The modifiers are "E", "O", ":", "::" and ":::". "E" and "O" are ignored.  No
-  # effect to result currently.
-  #
-  # Format directives:
-  #
-  #     Date (Year, Month, Day):
-  #       %Y - Year with century (can be negative, 4 digits at least)
-  #               -0001, 0000, 1995, 2009, 14292, etc.
-  #       %C - year / 100 (round down.  20 in 2009)
-  #       %y - year % 100 (00..99)
-  #
-  #       %m - Month of the year, zero-padded (01..12)
-  #               %_m  blank-padded ( 1..12)
-  #               %-m  no-padded (1..12)
-  #       %B - The full month name (``January'')
-  #               %^B  uppercased (``JANUARY'')
-  #       %b - The abbreviated month name (``Jan'')
-  #               %^b  uppercased (``JAN'')
-  #       %h - Equivalent to %b
-  #
-  #       %d - Day of the month, zero-padded (01..31)
-  #               %-d  no-padded (1..31)
-  #       %e - Day of the month, blank-padded ( 1..31)
-  #
-  #       %j - Day of the year (001..366)
-  #
-  #     Time (Hour, Minute, Second, Subsecond):
-  #       %H - Hour of the day, 24-hour clock, zero-padded (00..23)
-  #       %k - Hour of the day, 24-hour clock, blank-padded ( 0..23)
-  #       %I - Hour of the day, 12-hour clock, zero-padded (01..12)
-  #       %l - Hour of the day, 12-hour clock, blank-padded ( 1..12)
-  #       %P - Meridian indicator, lowercase (``am'' or ``pm'')
-  #       %p - Meridian indicator, uppercase (``AM'' or ``PM'')
-  #
-  #       %M - Minute of the hour (00..59)
-  #
-  #       %S - Second of the minute (00..60)
-  #
-  #       %L - Millisecond of the second (000..999)
-  #       %N - Fractional seconds digits, default is 9 digits (nanosecond)
-  #               %3N  millisecond (3 digits)   %15N femtosecond (15 digits)
-  #               %6N  microsecond (6 digits)   %18N attosecond  (18 digits)
-  #               %9N  nanosecond  (9 digits)   %21N zeptosecond (21 digits)
-  #               %12N picosecond (12 digits)   %24N yoctosecond (24 digits)
-  #
-  #     Time zone:
-  #       %z - Time zone as hour and minute offset from UTC (e.g. +0900)
-  #               %:z - hour and minute offset from UTC with a colon (e.g. +09:00)
-  #               %::z - hour, minute and second offset from UTC (e.g. +09:00:00)
-  #               %:::z - hour, minute and second offset from UTC
-  #                                                 (e.g. +09, +09:30, +09:30:30)
-  #       %Z - Equivalent to %:z (e.g. +09:00)
-  #
-  #     Weekday:
-  #       %A - The full weekday name (``Sunday'')
-  #               %^A  uppercased (``SUNDAY'')
-  #       %a - The abbreviated name (``Sun'')
-  #               %^a  uppercased (``SUN'')
-  #       %u - Day of the week (Monday is 1, 1..7)
-  #       %w - Day of the week (Sunday is 0, 0..6)
-  #
-  #     ISO 8601 week-based year and week number:
-  #     The week 1 of YYYY starts with a Monday and includes YYYY-01-04.
-  #     The days in the year before the first week are in the last week of
-  #     the previous year.
-  #       %G - The week-based year
-  #       %g - The last 2 digits of the week-based year (00..99)
-  #       %V - Week number of the week-based year (01..53)
-  #
-  #     Week number:
-  #     The week 1 of YYYY starts with a Sunday or Monday (according to %U
-  #     or %W).  The days in the year before the first week are in week 0.
-  #       %U - Week number of the year.  The week starts with Sunday.  (00..53)
-  #       %W - Week number of the year.  The week starts with Monday.  (00..53)
-  #
-  #     Seconds since the Unix Epoch:
-  #       %s - Number of seconds since 1970-01-01 00:00:00 UTC.
-  #       %Q - Number of milliseconds since 1970-01-01 00:00:00 UTC.
-  #
-  #     Literal string:
-  #       %n - Newline character (\n)
-  #       %t - Tab character (\t)
-  #       %% - Literal ``%'' character
-  #
-  #     Combination:
-  #       %c - date and time (%a %b %e %T %Y)
-  #       %D - Date (%m/%d/%y)
-  #       %F - The ISO 8601 date format (%Y-%m-%d)
-  #       %v - VMS date (%e-%^b-%Y)
-  #       %x - Same as %D
-  #       %X - Same as %T
-  #       %r - 12-hour time (%I:%M:%S %p)
-  #       %R - 24-hour time (%H:%M)
-  #       %T - 24-hour time (%H:%M:%S)
-  #       %+ - date(1) (%a %b %e %H:%M:%S %Z %Y)
-  #
-  # This method is similar to the strftime() function defined in ISO C and POSIX.
-  # Several directives (%a, %A, %b, %B, %c, %p, %r, %x, %X, %E*, %O* and %Z) are
-  # locale dependent in the function. However, this method is locale independent.
-  # So, the result may differ even if the same format string is used in other
-  # systems such as C. It is good practice to avoid %x and %X because there are
-  # corresponding locale independent representations, %D and %T.
-  #
-  # Examples:
-  #
-  #     d = DateTime.new(2007,11,19,8,37,48,"-06:00")
-  #                               #=> #<DateTime: 2007-11-19T08:37:48-0600 ...>
-  #     d.strftime("Printed on %m/%d/%Y")   #=> "Printed on 11/19/2007"
-  #     d.strftime("at %I:%M%p")            #=> "at 08:37AM"
-  #
-  # Various ISO 8601 formats:
-  #     %Y%m%d           => 20071119                  Calendar date (basic)
-  #     %F               => 2007-11-19                Calendar date (extended)
-  #     %Y-%m            => 2007-11                   Calendar date, reduced accuracy, specific month
-  #     %Y               => 2007                      Calendar date, reduced accuracy, specific year
-  #     %C               => 20                        Calendar date, reduced accuracy, specific century
-  #     %Y%j             => 2007323                   Ordinal date (basic)
-  #     %Y-%j            => 2007-323                  Ordinal date (extended)
-  #     %GW%V%u          => 2007W471                  Week date (basic)
-  #     %G-W%V-%u        => 2007-W47-1                Week date (extended)
-  #     %GW%V            => 2007W47                   Week date, reduced accuracy, specific week (basic)
-  #     %G-W%V           => 2007-W47                  Week date, reduced accuracy, specific week (extended)
-  #     %H%M%S           => 083748                    Local time (basic)
-  #     %T               => 08:37:48                  Local time (extended)
-  #     %H%M             => 0837                      Local time, reduced accuracy, specific minute (basic)
-  #     %H:%M            => 08:37                     Local time, reduced accuracy, specific minute (extended)
-  #     %H               => 08                        Local time, reduced accuracy, specific hour
-  #     %H%M%S,%L        => 083748,000                Local time with decimal fraction, comma as decimal sign (basic)
-  #     %T,%L            => 08:37:48,000              Local time with decimal fraction, comma as decimal sign (extended)
-  #     %H%M%S.%L        => 083748.000                Local time with decimal fraction, full stop as decimal sign (basic)
-  #     %T.%L            => 08:37:48.000              Local time with decimal fraction, full stop as decimal sign (extended)
-  #     %H%M%S%z         => 083748-0600               Local time and the difference from UTC (basic)
-  #     %T%:z            => 08:37:48-06:00            Local time and the difference from UTC (extended)
-  #     %Y%m%dT%H%M%S%z  => 20071119T083748-0600      Date and time of day for calendar date (basic)
-  #     %FT%T%:z         => 2007-11-19T08:37:48-06:00 Date and time of day for calendar date (extended)
-  #     %Y%jT%H%M%S%z    => 2007323T083748-0600       Date and time of day for ordinal date (basic)
-  #     %Y-%jT%T%:z      => 2007-323T08:37:48-06:00   Date and time of day for ordinal date (extended)
-  #     %GW%V%uT%H%M%S%z => 2007W471T083748-0600      Date and time of day for week date (basic)
-  #     %G-W%V-%uT%T%:z  => 2007-W47-1T08:37:48-06:00 Date and time of day for week date (extended)
-  #     %Y%m%dT%H%M      => 20071119T0837             Calendar date and local time (basic)
-  #     %FT%R            => 2007-11-19T08:37          Calendar date and local time (extended)
-  #     %Y%jT%H%MZ       => 2007323T0837Z             Ordinal date and UTC of day (basic)
-  #     %Y-%jT%RZ        => 2007-323T08:37Z           Ordinal date and UTC of day (extended)
-  #     %GW%V%uT%H%M%z   => 2007W471T0837-0600        Week date and local time and difference from UTC (basic)
-  #     %G-W%V-%uT%R%:z  => 2007-W47-1T08:37-06:00    Week date and local time and difference from UTC (extended)
-  #
-  # See also strftime(3) and ::strptime.
+  #   - strftime(format = '%F') -> string
+  # -->
+  # Returns a string representation of the date in `self`, formatted according the
+  # given `format`:
+  #
+  #     Date.new(2001, 2, 3).strftime # => "2001-02-03"
+  #
+  # For other formats, see [Formats for Dates and
+  # Times](rdoc-ref:strftime_formatting.rdoc).
   #
   def strftime: (?String format) -> String
 
   # <!-- rdoc-file=ext/date/date_core.c -->
-  # Returns a date object denoting the following day.
+  # Returns a new Date object representing the following day:
+  #
+  #     d = Date.new(2001, 2, 3)
+  #     d.to_s      # => "2001-02-03"
+  #     d.next.to_s # => "2001-02-04"
   #
   def succ: () -> Date
 
   # <!--
   #   rdoc-file=ext/date/date_core.c
-  #   - d.sunday?  ->  bool
+  #   - sunday? -> true or false
   # -->
-  # Returns true if the date is Sunday.
+  # Returns `true` if `self` is a Sunday, `false` otherwise.
   #
   def sunday?: () -> bool
 
   # <!--
   #   rdoc-file=ext/date/date_core.c
-  #   - d.thursday?  ->  bool
+  #   - thursday? -> true or false
   # -->
-  # Returns true if the date is Thursday.
+  # Returns `true` if `self` is a Thursday, `false` otherwise.
   #
   def thursday?: () -> bool
 
   # <!--
   #   rdoc-file=ext/date/date_core.c
-  #   - d.to_date  ->  self
+  #   - to_date -> self
   # -->
-  # Returns self.
+  # Returns `self`.
   #
   def to_date: () -> Date
 
@@ -1380,89 +1442,98 @@ class Date
   #   rdoc-file=ext/date/date_core.c
   #   - d.to_datetime  -> datetime
   # -->
-  # Returns a DateTime object which denotes self.
+  # Returns a DateTime whose value is the same as `self`:
+  #
+  #     Date.new(2001, 2, 3).to_datetime # => #<DateTime: 2001-02-03T00:00:00+00:00>
   #
   def to_datetime: () -> DateTime
 
   # <!--
   #   rdoc-file=ext/date/date_core.c
-  #   - d.to_s  ->  string
+  #   - to_s -> string
   # -->
-  # Returns a string in an ISO 8601 format. (This method doesn't use the expanded
-  # representations.)
+  # Returns a string representation of the date in `self` in [ISO 8601 extended
+  # date format](rdoc-ref:strftime_formatting.rdoc@ISO+8601+Format+Specifications)
+  # (`'%Y-%m-%d'`):
   #
-  #     Date.new(2001,2,3).to_s  #=> "2001-02-03"
+  #     Date.new(2001, 2, 3).to_s # => "2001-02-03"
   #
   def to_s: () -> String
 
   # <!--
   #   rdoc-file=ext/date/date_core.c
-  #   - d.to_time  ->  time
+  #   - to_time -> time
   # -->
-  # Returns a Time object which denotes self. If self is a julian date, convert it
-  # to a gregorian date before converting it to Time.
+  # Returns a new Time object with the same value as `self`; if `self` is a Julian
+  # date, derives its Gregorian date for conversion to the Time object:
+  #
+  #     Date.new(2001, 2, 3).to_time               # => 2001-02-03 00:00:00 -0600
+  #     Date.new(2001, 2, 3, Date::JULIAN).to_time # => 2001-02-16 00:00:00 -0600
   #
   def to_time: () -> Time
 
   # <!--
   #   rdoc-file=ext/date/date_core.c
-  #   - d.tuesday?  ->  bool
+  #   - tuesday? -> true or false
   # -->
-  # Returns true if the date is Tuesday.
+  # Returns `true` if `self` is a Tuesday, `false` otherwise.
   #
   def tuesday?: () -> bool
 
   # <!--
   #   rdoc-file=ext/date/date_core.c
-  #   - d.upto(max)              ->  enumerator
-  #   - d.upto(max){|date| ...}  ->  self
+  #   - upto(max){|date| ... } -> self
   # -->
-  # This method is equivalent to step(max, 1){|date| ...}.
+  # Equivalent to #step with arguments `max` and `1`.
   #
   def upto: (Date max) { (Date) -> untyped } -> Date
           | (Date max) -> ::Enumerator[Date, Date]
 
   # <!--
   #   rdoc-file=ext/date/date_core.c
-  #   - d.wday  ->  fixnum
+  #   - wday -> integer
   # -->
-  # Returns the day of week (0-6, Sunday is zero).
+  # Returns the day of week in range (0..6); Sunday is 0:
   #
-  #     Date.new(2001,2,3).wday           #=> 6
+  #     Date.new(2001, 2, 3).wday # => 6
   #
   def wday: () -> Integer
 
   # <!--
   #   rdoc-file=ext/date/date_core.c
-  #   - d.wednesday?  ->  bool
+  #   - wednesday? -> true or false
   # -->
-  # Returns true if the date is Wednesday.
+  # Returns `true` if `self` is a Wednesday, `false` otherwise.
   #
   def wednesday?: () -> bool
 
   # <!-- rdoc-file=ext/date/date_core.c -->
-  # This method is equivalent to strftime('%F').
+  # Equivalent to #strftime with argument `'%Y-%m-%d'` (or its [shorthand
+  # form](rdoc-ref:strftime_formatting.rdoc@Shorthand+Conversion+Specifiers)
+  # `'%F'`);
+  #
+  #     Date.new(2001, 2, 3).iso8601 # => "2001-02-03"
   #
   def xmlschema: () -> String
 
   # <!--
   #   rdoc-file=ext/date/date_core.c
-  #   - d.yday  ->  fixnum
+  #   - yday -> integer
   # -->
-  # Returns the day of the year (1-366).
+  # Returns the day of the year, in range (1..366):
   #
-  #     Date.new(2001,2,3).yday           #=> 34
+  #     Date.new(2001, 2, 3).yday # => 34
   #
   def yday: () -> Integer
 
   # <!--
   #   rdoc-file=ext/date/date_core.c
-  #   - d.year  ->  integer
+  #   - year -> integer
   # -->
-  # Returns the year.
+  # Returns the year:
   #
-  #     Date.new(2001,2,3).year           #=> 2001
-  #     (Date.new(1,1,1) - 1).year        #=> 0
+  #     Date.new(2001, 2, 3).year    # => 2001
+  #     (Date.new(1, 1, 1) - 1).year # => 0
   #
   def year: () -> Integer
 end