[ruby/date] [DOC] Enhanced RDoc (https://github.com/ruby/date/pull/57)

All things commercial.

https://github.com/ruby/date/commit/9d3bc61728

ext/date/date_core.c

@@ -2732,7 +2732,7 @@ date_s__valid_commercial_p(int argc, VALUE *argv, VALUE klass)
 
 /*
  * call-seq:
- *    Date.valid_commercial?(cwyear, cweek, cwday, start = Date::ITALY) -> true or false
+ *   Date.valid_commercial?(cwyear, cweek, cwday, start = Date::ITALY) -> true or false
  *
  * Returns +true+ if the arguments define a valid commercial date,
  * +false+ otherwise:
@@ -2740,6 +2740,8 @@ date_s__valid_commercial_p(int argc, VALUE *argv, VALUE klass)
  *   Date.valid_commercial?(2001, 5, 6) # => true
  *   Date.valid_commercial?(2001, 5, 8) # => false
  *
+ * See Date.commercial.
+ *
  * See {Argument start}[rdoc-ref:Date@Argument+start].
  *
  * Related: Date.jd, Date.commercial.
@@ -3527,19 +3529,47 @@ date_initialize(int argc, VALUE *argv, VALUE self)
 
 /*
  * call-seq:
- *    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.
  *
- * 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.
+ * Argument +cwyear+ gives the year, and should be an integer.
  *
- *    Date.commercial(2001)	#=> #<Date: 2001-01-01 ...>
- *    Date.commercial(2002)	#=> #<Date: 2001-12-31 ...>
- *    Date.commercial(2001,5,6)	#=> #<Date: 2001-02-03 ...>
+ * 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:
  *
- * See also ::jd and ::new.
+ *   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"
+ *
+ * - Otherwise, the first week is the week of January 1,
+ *   which may mean some of the days fall on the year before:
+ *
+ *     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 {Argument start}[rdoc-ref:Date@Argument+start].
+ *
+ * Related: Date.jd, Date.new, Date.ordinal.
  */
 static VALUE
 date_s_commercial(int argc, VALUE *argv, VALUE klass)
@@ -5226,12 +5256,14 @@ d_lite_day_fraction(VALUE self)
 
 /*
  * call-seq:
- *    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
  */
 static VALUE
 d_lite_cwyear(VALUE self)
@@ -5242,11 +5274,13 @@ d_lite_cwyear(VALUE self)
 
 /*
  * call-seq:
- *    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
  */
 static VALUE
 d_lite_cweek(VALUE self)
@@ -5257,11 +5291,14 @@ d_lite_cweek(VALUE self)
 
 /*
  * call-seq:
- *    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
  */
 static VALUE
 d_lite_cwday(VALUE self)