Bug #10049: RDoc bug for time format

• Status: Closed
• Assignee: zzak (zzak _)
• Target version: 2.2.0
• ruby -v: 2.1.1
• Backport: 2.0.0: UNKNOWN, 2.1: UNKNOWN

[sawa (Tsuyoshi Sawada)]

A bug report https://bugs.ruby-lang.org/issues/8941 notes a contradiction between RDoc and Ruby behavior. If tadayoshi funaba is correct and %Y should be able to accept digits less than four, then the following RDoc description is a bug, and should be corrected.

%Y - Year with century (can be negative, 4 digits at least)

[jaredbeck (Jared Beck)]

The cited line of documentation:

%Y - Year with century (can be negative, 4 digits at least)

was taken from strftime (time.c:4395). Therefore, the phrase "4 digits at least" refers to output.

However, the documentation for Time.strptime says, simply:

%Y :: Year with century

and does not specify a number of input digits. (See lib/time.rb:420)

Perhaps the documentation for Time.strptime could be elaborated, but I don't think it is incorrect.

[sawa (Tsuyoshi Sawada)]

However, the documentation for Time.strptime says, simply:

%Y :: Year with century

I don't understand how you interpreted the phrase "with century". In order to express a year with century, there has to be the third digit (hundreds), which means there has to be at least three digits. The documentation still does not match the Ruby behavior. Or, if there is a different interpretation of this phrase, at best it is misleading. Something like "full year" may work better.

But it is still misleading that the same %Y means a different thing for input and output.

[phluid61 (Matthew Kerwin)]

Tsuyoshi Sawada wrote:

However, the documentation for Time.strptime says, simply:

%Y :: Year with century

I don't understand how you interpreted the phrase "with century". In order to express a year with century, there has to be the third digit (hundreds), which means there has to be at least three digits. The documentation still does not match the Ruby behavior.

No, it doesn't mean that there must be a third digit, it means that the century is always explicit, never implied. This includes absence. For example, the value "93" means unambiguously A.D. 93, never 1993 (or any other year). In contrast, according to its documentation strftime would produce "0093" -- which it does.

[sawa (Tsuyoshi Sawada)]

However, the documentation for Time.strptime says, simply:
%Y :: Year with century

Actually, I cannot find such description. I searched in these docs:

• Ruby 1.9.3 Time (http://ruby-doc.org/stdlib-1.9.3/libdoc/date/rdoc/Time.html)
• Ruby 1.9.3 Date (http://ruby-doc.org/stdlib-1.9.3/libdoc/date/rdoc/Date.html)
• Ruby 1.9.3 DateTime (http://ruby-doc.org/stdlib-1.9.3/libdoc/date/rdoc/DateTime.html#method-c-strptime)
• Ruby 2.1.1 Time (http://ruby-doc.org/stdlib-2.1.1/libdoc/date/rdoc/Time.html)
• Ruby 2.1.1 Date (http://ruby-doc.org/stdlib-2.1.1/libdoc/date/rdoc/Date.html)
• Ruby 2.1.1 DateTime (http://ruby-doc.org/stdlib-2.1.1/libdoc/date/rdoc/DateTime.html)

but not of them has such description. Am I looking in the wrong place?

[jaredbeck (Jared Beck)]

However, the documentation for Time.strptime says, simply:
%Y :: Year with century

Actually, I cannot find such description.

I don't see it at ruby-doc.org, either. Check out lib/time.rb:420 (https://github.com/ruby/ruby/blob/f75b676cc4f5411c4c1aa8cc9cb48d5dd665af6f/lib/time.rb#L420)

[sawa (Tsuyoshi Sawada)]

Jared Beck wrote:

I don't see it at ruby-doc.org, either. Check out lib/time.rb:420 (https://github.com/ruby/ruby/blob/f75b676cc4f5411c4c1aa8cc9cb48d5dd665af6f/lib/time.rb#L420)

My bug report is about the documentation. It is about what appears in the document. It does not matter what is in the source code. Furthermore, ordinary people do not see the source code when there is a document. And if the document only lists the format once (which you claim to be only for output), it is very natural to take that as the format regardless of input or output.

Either way, it is a documentation bug.

But it is helpful that you made clear the cause of the problem.

[zzak (zzak _)]

• Category set to doc
• Status changed from Open to Assigned
• Assignee set to zzak (zzak _)
• Target version set to 2.2.0

[zzak (zzak _)]

• Status changed from Assigned to Closed
• % Done changed from 0 to 100

Applied in changeset r46983.

---

Fix ticket number from r46982, should be [Bug #10049]