Bug #10049
closedRDoc bug for time format
Description
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)
Updated by jaredbeck (Jared Beck) about 10 years ago
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.
Updated by sawa (Tsuyoshi Sawada) about 10 years ago
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.
Updated by phluid61 (Matthew Kerwin) about 10 years ago
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.
Updated by sawa (Tsuyoshi Sawada) about 10 years ago
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?
Updated by jaredbeck (Jared Beck) about 10 years ago
However, the documentation for Time.strptime says, simply:
%Y :: Year with centuryActually, 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)
Updated by sawa (Tsuyoshi Sawada) about 10 years ago
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.
Updated by zzak (zzak _) about 10 years ago
- Category set to doc
- Status changed from Open to Assigned
- Assignee set to zzak (zzak _)
- Target version set to 2.2.0
Updated by zzak (zzak _) about 10 years ago
- Status changed from Assigned to Closed
- % Done changed from 0 to 100