Project

General

Profile

Bug #14004

ri confused by method aliases and by Queue versus Thread::Queue

Added by kernigh (George Koehler) almost 2 years ago. Updated almost 2 years ago.

Status:
Open
Priority:
Normal
Assignee:
-
Target version:
-
ruby -v:
ruby 2.5.0dev (2017-10-10 trunk 60155) [x86_64-openbsd6.2]
[ruby-core:83219]

Description

ri in Ruby trunk fails to find documentation for some methods.

Array#append and Array#prepend are new in trunk. ri knows that these methods exist, but has no document for them.

$ ri Array#append

= Array#append

(from ruby core)
------------------------------------------------------------------------------
  append(*args)

------------------------------------------------------------------------------

The same problem happens with all methods from rb_define_alias() in Ruby's source code. For example, Array#size, IO#to_i, Hash#to_s, and Thread#inspect have no document. These are all aliases of other methods that have document.

There is another problem with Queue, an alias for Thread::Queue. ri doesn't know that Queue has methods.

$ ri Queue#push
Nothing known about Queue#push

The command ri Queue shows the document for the class, but it has no methods. The command ri Thread::Queue shows methods, but no class document. The same problem happens with other classes in rthread_sync.c, like Mutex.

History

Updated by shevegen (Robert A. Heiler) almost 2 years ago

I think I noticed that in regards to aliased-method names some time ago, but it does not appear with all aliased names, right? For example, Array#collect and Array#map was always there. I myself only use the online docu though, or only parts of ri, e. g. via method_source (for ruby addons that is).

If one goes to https://ruby-doc.org/core/Hash.html#method-i-to_s, the docu shows in italic letters:

"Alias for: inspect"

For Array#map and collect, it is identical docu:

https://ruby-doc.org/core/Array.html#method-i-map

Not sure why ri gets confused sometimes and sometimes not.

Updated by kernigh (George Koehler) almost 2 years ago

I run make html in my build of Ruby trunk.
This puts the HTML in .ext/html,
so I run firefox .ext/html/index.html to view it.

I can confirm that the HTML docs do understand most aliases. For example, Array#append says, Alias for: push, in italic; and #push lists #append as an alias. So it seems that the HTML can handle aliases, but ri can't handle them. Bug in ri?

The HTML still doesn't understand that Queue and Thread::Queue are the same. The class document is under Queue and the method documents are under Thread::Queue. This is the same problem as ri.

Array#collect and Array#map have copies of the same doc, because the C code (in array.c) defines both methods using rb_define_method().

    rb_define_method(rb_cArray, "collect", rb_ary_collect, 0);
...
    rb_define_method(rb_cArray, "map", rb_ary_collect, 0);

This is different from Array#append or Array#prepend, where the C code uses rb_define_alias().

    rb_define_method(rb_cArray, "push", rb_ary_push_m, -1);
    rb_define_alias(rb_cArray,  "append", "push");
...
    rb_define_method(rb_cArray, "unshift", rb_ary_unshift_m, -1);
    rb_define_alias(rb_cArray,  "prepend", "unshift");

Updated by kernigh (George Koehler) almost 2 years ago

rdoc also confuses class Gem::RDoc with class RDoc. The command ri RDoc shows the description of both Gem::RDoc and RDoc as if they were one class. The command ri Gem::RDoc says, "Nothing known about Gem::RDoc". The HTML from make html documents Gem::RDoc as RDoc and has no document for the real RDoc.

The document for RDoc::RDoc seems fine.

Also available in: Atom PDF