Bug #10049

RDoc bug for time format

Added by Tsuyoshi Sawada about 1 year ago. Updated about 1 year ago.

[ruby-core:63779]
Status:Closed
Priority:Normal
Assignee:Zachary Scott
ruby -v:2.1.1 Backport:2.0.0: UNKNOWN, 2.1: UNKNOWN

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)

Associated revisions

Revision 46983
Added by Zachary Scott about 1 year ago

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

Revision 46983
Added by Zachary Scott about 1 year ago

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

History

#1 Updated by Jared Beck about 1 year 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.

#2 Updated by Tsuyoshi Sawada about 1 year 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.

#3 Updated by Matthew Kerwin about 1 year 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.

#4 Updated by Tsuyoshi Sawada about 1 year ago

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

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

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

#5 Updated by Jared Beck about 1 year ago

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)

#6 Updated by Tsuyoshi Sawada about 1 year 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.

#7 Updated by Zachary Scott about 1 year ago

  • Category set to doc
  • Status changed from Open to Assigned
  • Assignee set to Zachary Scott
  • Target version set to current: 2.2.0

#8 Updated by Zachary Scott about 1 year ago

  • 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]

Also available in: Atom PDF