Bug #13193: [DOC] Revise docs for Date and DateTime

• Status: Closed
• Assignee: -
• Target version: -
• ruby -v: ruby 2.4.0p0 (2016-12-24 revision 57164) [i686-linux]
• Backport: 2.2: DONE, 2.3: REQUIRED, 2.4: DONE

[stomar (Marcus Stollsteimer)]

ext/date/date_core.c: [DOC] revise docs for Date and DateTime

* fix malformed rdoc for Date#today, Date._strptime,
  and DateTime._strptime
* add code examples for Date#<< and Date#>> to demonstrate
  that different dates can result in the same return value
* use Date::ITALY in call-seq instead of only ITALY
* fix some copy/paste mistakes where Date should be DateTime
* fix various errors and grammar
* fix cross references and formatting

[nobu (Nobuyoshi Nakada)]

Thank you for the great contribution.
Just curious what differs in examples of Jan 30 and Jan 31.

+ *    Date.new(2001,1,30) >>  1   #=> #<Date: 2001-02-28 ...>
+ *    Date.new(2001,1,31) >>  1   #=> #<Date: 2001-02-28 ...>

[nobu (Nobuyoshi Nakada)]

To "demonstrate that different dates can result in the same return value", isn't Date.new(2001,1,28) better?

[nobu (Nobuyoshi Nakada)]

• Status changed from Open to Closed

Applied in changeset r57549.

---

date_core.c: [DOC] revise docs [ci skip]

• fix malformed rdoc for Date#today, Date._strptime,
  and DateTime._strptime
• add code examples for Date#<< and Date#>> to demonstrate
  that different dates can result in the same return value
• use Date::ITALY in call-seq instead of only ITALY
• fix some copy/paste mistakes where Date should be DateTime
• fix various errors and grammar
• fix cross references and formatting

[ruby-core:79433] [Bug #13193]
Author: Marcus Stollsteimer [e-mail]

[stomar (Marcus Stollsteimer)]

Nobuyoshi Nakada wrote:

To "demonstrate that different dates can result in the same return value", isn't Date.new(2001,1,28) better?

Agreed.
Maybe there even should be an extra paragraph that explicitly points this out.

And maybe also the following, possibly surprising sort of behavior should be mentioned:

require "date"

date = Date.new(2001,1,31)
12.times { date >>= 1 }
date.to_s   # => "2002-01-28"

date = Date.new(2001,1,31)
date >>= 12
date.to_s   # => "2002-01-31"

Should I prepare a patch?

[stomar (Marcus Stollsteimer)]

A shorter version:

Date.new(2001,1,31) >> 2        # => #<Date: 2001-03-31 ...>
Date.new(2001,1,31) >> 1 >> 1   # => #<Date: 2001-03-28 ...>

Update: See #13225.

[naruse (Yui NARUSE)]

• Backport changed from 2.2: UNKNOWN, 2.3: UNKNOWN, 2.4: UNKNOWN to 2.2: UNKNOWN, 2.3: UNKNOWN, 2.4: DONE

ruby_2_4 r57904 merged revision(s) 57549.

[nagachika (Tomoyuki Chikanaga)]

• Backport changed from 2.2: UNKNOWN, 2.3: UNKNOWN, 2.4: DONE to 2.2: REQUIRED, 2.3: REQUIRED, 2.4: DONE

[usa (Usaku NAKAMURA)]

• Backport changed from 2.2: REQUIRED, 2.3: REQUIRED, 2.4: DONE to 2.2: DONE, 2.3: REQUIRED, 2.4: DONE

ruby_2_2 r58101 merged revision(s) 57549.