Project

General

Profile

Feature #12208

Improve ri command

Added by naruse (Yui NARUSE) over 1 year ago. Updated over 1 year ago.

Status:
Open
Priority:
Normal
Assignee:
-
Target version:
-
[ruby-core:74493]

Description

Ruby has well documented in rdoc.
It also has a frontend CLI.

But people seems not using ri...

At first, write your request here to improve ri command!

Sample ri.png (44.7 KB) Sample ri.png kgrz (Kashyap K), 03/23/2016 06:25 AM

History

#1 [ruby-core:74494] Updated by kgrz (Kashyap K) over 1 year ago

We could add the ri commands for each method on the Ruby doc HTML pages at just under the method signature line (like shown in the image attached) or some place else. That way anyone who visits the Ruby doc website will come to know the ri tool in general. And they might end up using it next time onwards. One more side-effect of this is that the difference between the 'dot' and 'pound' style usage (String#to_s and Kernel.eval) may become clear for people new to the language.

#2 [ruby-core:74499] Updated by shevegen (Robert A. Heiler) over 1 year ago

ri is a bit weird, perhaps it is just that I got used to it not being that hugely important back in 2003 or
2004 or so.

I had to ask on stackoverflow how to obtain information from ri/rdoc, for use in a REPL.

The API is something like:

RDoc::RI::Driver.process_args

It works fine, too, but finding this part is ... not really great. I'd wish there would be class methods for
this on the "RDoc." namespace directly, something readable like "RDoc.obtain_documentation_for(:this_method)"
or just something similar.

Anyway I very much support Yui Naruse's issue tracker here. The better ri, the more people will use it!

I would also like to suggest to style the http://ruby-doc.org/core-2.3.0/ page better.

For 2.3.0 it may be ok, but the whole ruby-doc.org site seems to have some missing stuff or links and
it is a bit confusing to use.

Personally for my own projects, I do not use rdoc. I do document my methods a lot, mind you, I just
do not use ri/rdoc much at all because I do not find them too useful. I have no idea what else to
use - right now I am settling for simply writing documentation into local .cgi pages which can
generate a .html page which can be used for autogenerating a .pdf file using wkhtmltopdf

This is not really pretty either but at least I get to style and design things how I want to.
(I would love to have a unified way to present both normal user documentation AND documentation
for the developer; I very much like the "click to view source" functionality, that part is
nice to have. If people want to obtain that information, they just click on it, and if they
do not need it, it is hidden by default.)

Anyway, not sure if this is helpful, just some semi-random thoughts from me.

#3 [ruby-core:74503] Updated by duerst (Martin Dürst) over 1 year ago

I think it would be great to somehow integrate the 'do_you_mean' functionality into ri.

Also, a bit more interactivity may help. As an example, if I write "ri each", I get just a concatenation of the doc for many different 'each' methods. It would be better to get a list, and a way to select a specific one.

Also, being able to use something like ri inside irb may be helpful. Maybe that already exists, and I just don't know.

#4 [ruby-core:74589] Updated by stomar (Marcus Stollsteimer) over 1 year ago

I like and use ri. It's nice that it works offline but there are some inconveniences; two of them that come to my mind right now:

  • For common method names the output is rather confusing, implementations from core and stdlib and installed gems are listed without any logic order (at least to me).

  • ri doesn't give the full namespace hierarchy of a given method, so it's not always easy to get more information on the class that defines a specific method. Example: ri fetch points to the Row class ("Implementation from Row"), but ri Row doesn't give any result (only ri CSV::Row does).

Regarding the suggestion of showing the ri command for every method in the HTML docs: for me that would produce too much noise.

Also available in: Atom PDF