From 1683c1f031823a8bd16ff100a9513bc1ff20e9c4 Mon Sep 17 00:00:00 2001 From: BurdetteLamar Date: Fri, 29 Jul 2022 10:24:53 -0500 Subject: [PATCH 1/3] Enhanced RDoc --- ext/date/date_core.c | 136 ++++++++++++++++++++++++++++--------------- 1 file changed, 88 insertions(+), 48 deletions(-) diff --git a/ext/date/date_core.c b/ext/date/date_core.c index 9214333..b82497d 100644 --- a/ext/date/date_core.c +++ b/ext/date/date_core.c @@ -6732,13 +6732,13 @@ cmp_dd(VALUE self, VALUE other) * * d <=> DateTime.new(2022, 7, 26) # => 1 * d <=> DateTime.new(2022, 7, 27) # => 0 - * d <=> DateTime.new(2022, 7, 29) # => -1 + * d <=> DateTime.new(2022, 7, 28) # => -1 * - * - A numeric (compares self.ajd to +other+): + * - A numeric (compares self.jd to +other+): * - * d <=> 2459789 # => -1 * d <=> 2459788 # => -1 * d <=> 2459787 # => 1 + * d <=> 2459786 # => -1 * d <=> d.ajd # => 0 * * - Any other object: @@ -6804,20 +6804,39 @@ equal_gen(VALUE self, VALUE other) /* * call-seq: - * d === other -> bool - * - * Returns true if they are the same day. - * - * 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 + * self === other -> true, false, or nil. + * + * Returns +true+ if +self+ and +other+ represent the same date, + * +false+ if not, +nil+ if the two are incommensurate. + * + * Argument +other+ may be: + * + * - Another \Date object: + * + * d = Date.new(2022, 7, 27) # => # + * prev_date = d.prev_day # => # + * next_date = d.next_day # => # + * d === prev_date # => false + * d === d # => true + * d === next_date # => false + * + * - A DateTime object: + * + * 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 incommensurate object: + * + * d === Object.new # => nil + * */ static VALUE d_lite_equal(VALUE self, VALUE other) @@ -6880,12 +6899,14 @@ static VALUE strftimev(const char *, VALUE, /* * call-seq: - * 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}[https://docs.ruby-lang.org/en/master/strftime_formatting_rdoc.html#label-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" */ static VALUE d_lite_to_s(VALUE self) @@ -6966,14 +6987,13 @@ mk_inspect(union DateData *x, VALUE klass, VALUE to_s) /* * call-seq: - * 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.new(2001,2,3).inspect - * #=> "#" - * DateTime.new(2001,2,3,4,5,6,'-7').inspect - * #=> "#" */ static VALUE d_lite_inspect(VALUE self) @@ -7155,9 +7175,9 @@ date_strftime_internal(int argc, VALUE *argv, VALUE self, /* * call-seq: - * strftime(format = '%F') -> string + * strftime(format = '%F') -> string * - * Returns a string representation of +self+, + * Returns a string representation of the date in +self+, * formatted according the given +format+: * * Date.today.strftime # => "2022-07-01" @@ -7192,13 +7212,15 @@ strftimev(const char *fmt, VALUE self, /* * call-seq: - * 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}[https://docs.ruby-lang.org/en/master/strftime_formatting_rdoc.html#label-Shorthand+Conversion+Specifiers] + * '%c'); * - * See also asctime(3) or ctime(3). + * Date.today.asctime # => "Fri Jul 29 00:00:00 2022" + * + * Date#ctime is an alias for Date#asctime. */ static VALUE d_lite_asctime(VALUE self) @@ -7208,10 +7230,15 @@ d_lite_asctime(VALUE self) /* * call-seq: - * d.iso8601 -> string - * d.xmlschema -> string + * iso8601 -> string + * + * Equivalent to #strftime with argument '%Y-%m-%d' + * (or its {shorthand form}[https://docs.ruby-lang.org/en/master/strftime_formatting_rdoc.html#label-Shorthand+Conversion+Specifiers] + * '%F'); * - * This method is equivalent to strftime('%F'). + * Date.today.iso8601 # => "2022-07-29" + * + * Date#xmlschema is an alias for Date#iso8601. */ static VALUE d_lite_iso8601(VALUE self) @@ -7221,9 +7248,13 @@ d_lite_iso8601(VALUE self) /* * call-seq: - * d.rfc3339 -> string + * rfc3339 -> string + * + * Equivalent to #strftime with argument '%FT%T%:z'; + * see {Formats for Dates and Times}[https://docs.ruby-lang.org/en/master/strftime_formatting_rdoc.html]: + * + * Date.today.rfc3339 # => "2022-07-29T00:00:00+00:00" * - * This method is equivalent to strftime('%FT%T%:z'). */ static VALUE d_lite_rfc3339(VALUE self) @@ -7233,10 +7264,14 @@ d_lite_rfc3339(VALUE self) /* * call-seq: - * d.rfc2822 -> string - * d.rfc822 -> string + * rfc2822 -> string + * + * Equivalent to #strftime with argument '%a, %-d %b %Y %T %z'; + * see {Formats for Dates and Times}[https://docs.ruby-lang.org/en/master/strftime_formatting_rdoc.html]: + * + * Date.today.rfc2822 # => "Fri, 29 Jul 2022 00:00:00 +0000" * - * This method is equivalent to strftime('%a, %-d %b %Y %T %z'). + * Date#rfc822 is an alias for Date#rfc2822. */ static VALUE d_lite_rfc2822(VALUE self) @@ -7246,10 +7281,13 @@ d_lite_rfc2822(VALUE self) /* * call-seq: - * d.httpdate -> string + * httpdate -> string + * + * Equivalent to #strftime with argument '%a, %d %b %Y %T GMT'; + * see {Formats for Dates and Times}[https://docs.ruby-lang.org/en/master/strftime_formatting_rdoc.html]: + * + * Date.today.httpdate # => "Fri, 29 Jul 2022 00:00:00 GMT" * - * This method is equivalent to strftime('%a, %d %b %Y %T GMT'). - * See also RFC 2616. */ static VALUE d_lite_httpdate(VALUE self) @@ -7300,11 +7338,13 @@ jisx0301_date_format(char *fmt, size_t size, VALUE jd, VALUE y) /* * call-seq: - * 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.today.jisx0301 # => "R04.07.29" * - * Date.new(2001,2,3).jisx0301 #=> "H13.02.03" */ static VALUE d_lite_jisx0301(VALUE self) From 93ec4b2f611598ea226cf6bc2f7633d00d89a31d Mon Sep 17 00:00:00 2001 From: BurdetteLamar Date: Fri, 29 Jul 2022 11:11:42 -0500 Subject: [PATCH 2/3] Enhanced RDoc --- ext/date/date_core.c | 30 ++++++++++++++++-------------- 1 file changed, 16 insertions(+), 14 deletions(-) diff --git a/ext/date/date_core.c b/ext/date/date_core.c index b82497d..25b5fc5 100644 --- a/ext/date/date_core.c +++ b/ext/date/date_core.c @@ -6344,9 +6344,9 @@ d_lite_prev_day(int argc, VALUE *argv, VALUE self) * * Returns a new \Date object representing the following day: * - * d = Date.today - * d.to_s # => "2022-07-11" - * d.next.to_s # => "2022-07-12" + * d = Date.new(2001, 2, 3) + * d.to_s # => "2001-02-03" + * d.next.to_s # => "2001-02-04" * * Date#succ is an alias for Date#next. */ @@ -6734,7 +6734,7 @@ cmp_dd(VALUE self, VALUE other) * d <=> DateTime.new(2022, 7, 27) # => 0 * d <=> DateTime.new(2022, 7, 28) # => -1 * - * - A numeric (compares self.jd to +other+): + * - A numeric (compares self.ajd to +other+): * * d <=> 2459788 # => -1 * d <=> 2459787 # => 1 @@ -6807,7 +6807,7 @@ equal_gen(VALUE self, VALUE other) * self === other -> true, false, or nil. * * Returns +true+ if +self+ and +other+ represent the same date, - * +false+ if not, +nil+ if the two are incommensurate. + * +false+ if not, +nil+ if the two are not comparable. * * Argument +other+ may be: * @@ -6833,7 +6833,7 @@ equal_gen(VALUE self, VALUE other) * d === 2459786 # => false * d === d.jd # => true * - * - An incommensurate object: + * - An object not comparable: * * d === Object.new # => nil * @@ -7180,7 +7180,7 @@ date_strftime_internal(int argc, VALUE *argv, VALUE self, * Returns a string representation of the date in +self+, * formatted according the given +format+: * - * Date.today.strftime # => "2022-07-01" + * Date.new(2001, 2, 3).strftime # => "2001-02-03" * * For other formats, see * {Formats for Dates and Times}[https://docs.ruby-lang.org/en/master/strftime_formatting_rdoc.html]. @@ -7216,9 +7216,11 @@ strftimev(const char *fmt, VALUE self, * * Equivalent to #strftime with argument '%a %b %e %T %Y' * (or its {shorthand form}[https://docs.ruby-lang.org/en/master/strftime_formatting_rdoc.html#label-Shorthand+Conversion+Specifiers] - * '%c'); + * '%c'): + * + * Date.new(2001, 2, 3).asctime # => "Sat Feb 3 00:00:00 2001" * - * Date.today.asctime # => "Fri Jul 29 00:00:00 2022" + * See {asctime}[https://linux.die.net/man/3/asctime]. * * Date#ctime is an alias for Date#asctime. */ @@ -7236,7 +7238,7 @@ d_lite_asctime(VALUE self) * (or its {shorthand form}[https://docs.ruby-lang.org/en/master/strftime_formatting_rdoc.html#label-Shorthand+Conversion+Specifiers] * '%F'); * - * Date.today.iso8601 # => "2022-07-29" + * Date.new(2001, 2, 3).iso8601 # => "2001-02-03" * * Date#xmlschema is an alias for Date#iso8601. */ @@ -7253,7 +7255,7 @@ d_lite_iso8601(VALUE self) * Equivalent to #strftime with argument '%FT%T%:z'; * see {Formats for Dates and Times}[https://docs.ruby-lang.org/en/master/strftime_formatting_rdoc.html]: * - * Date.today.rfc3339 # => "2022-07-29T00:00:00+00:00" + * Date.new(2001, 2, 3).rfc3339 # => "2001-02-03T00:00:00+00:00" * */ static VALUE @@ -7269,7 +7271,7 @@ d_lite_rfc3339(VALUE self) * Equivalent to #strftime with argument '%a, %-d %b %Y %T %z'; * see {Formats for Dates and Times}[https://docs.ruby-lang.org/en/master/strftime_formatting_rdoc.html]: * - * Date.today.rfc2822 # => "Fri, 29 Jul 2022 00:00:00 +0000" + * Date.new(2001, 2, 3).rfc2822 # => "Sat, 3 Feb 2001 00:00:00 +0000" * * Date#rfc822 is an alias for Date#rfc2822. */ @@ -7286,7 +7288,7 @@ d_lite_rfc2822(VALUE self) * Equivalent to #strftime with argument '%a, %d %b %Y %T GMT'; * see {Formats for Dates and Times}[https://docs.ruby-lang.org/en/master/strftime_formatting_rdoc.html]: * - * Date.today.httpdate # => "Fri, 29 Jul 2022 00:00:00 GMT" + * Date.new(2001, 2, 3).httpdate # => "Sat, 03 Feb 2001 00:00:00 GMT" * */ static VALUE @@ -7343,7 +7345,7 @@ jisx0301_date_format(char *fmt, size_t size, VALUE jd, VALUE y) * Returns a string representation of the date in +self+ * in JIS X 0301 format. * - * Date.today.jisx0301 # => "R04.07.29" + * Date.new(2001, 2, 3).jisx0301 # => "H13.02.03" * */ static VALUE From 39707c0f20a8a2849ea10561d0e54ee9abc9175a Mon Sep 17 00:00:00 2001 From: BurdetteLamar Date: Fri, 29 Jul 2022 12:33:59 -0500 Subject: [PATCH 3/3] Enhanced RDoc --- ext/date/date_core.c | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/ext/date/date_core.c b/ext/date/date_core.c index 25b5fc5..d804819 100644 --- a/ext/date/date_core.c +++ b/ext/date/date_core.c @@ -6738,7 +6738,7 @@ cmp_dd(VALUE self, VALUE other) * * d <=> 2459788 # => -1 * d <=> 2459787 # => 1 - * d <=> 2459786 # => -1 + * d <=> 2459786 # => 1 * d <=> d.ajd # => 0 * * - Any other object: