Feature #16373: RDoc for some of the Kernel methods cannot be found in Kernel module

• Status: Open
• Assignee: -
• Target version: -
• Tags: lib

[soutaro (Soutaro Matsumoto)]

RDoc documentations for some of the Kernel methods including Kernel#then are registered as Object methods. I'd like to propose to move Kernel methods listed in Object class to Kernel class.

The following ri results are confusing to me because the Object methods are defined in Kernel module technically.

$ ri Kernel#then
Nothing known about Kernel#then
$ ri Object#then
[Prints documentation]

This is because of the implementation of RDoc that it treats Kernel methods as if they are defined in Object.

• https://github.com/ruby/rdoc/blob/acfb829917336ecbca6036437918c29319db7c04/lib/rdoc/parser/c.rb#L508

I'd like to disable the assignment and make Kernel methods listed in Kernel module.

Pros

• The RDoc structure is more clear and precise
  • (This is essential to me that it makes easier to generate annotations for RBS files.)
• Both of ri Kernel#then and ri Object#then print the documentation

Cons

• The document of Object class will be almost empty, which may cause confusion for readers while there is a link to included module, Kernel

[zverok (Victor Shepelev)]

I believe that there is some complicated discrepancy between where the method "defined" physically and where it "belongs" logically (though, it is not completely clear to me why some of the methods defined where they are).

If we take two examples: #then and #puts:

1. Both are defined in Kernel
2. #then makes more sense as method every object have, so you can any_object.then { ... }; it doesn't make much sense (even if possible) to do just then { ... } (UPD: ugh, it isn't even possible, parser thinks it is then-as-keyword... Well, OK, tap { ... } is possible, but almost meaningless)
3. #puts makes more sense as method available everywhere without explicit receiver; in fact 1.puts 'foo' is NOT possible (puts is private)

I believe that if both would be documented as Kernel methods, it would be highly misleading.

So, in fact, I believe the real question is "why #then defined in Kernel and not in Object" :) But probably there is some good justification for it (because lot of other making-sense-only-with-receiver methods are also defined there).

[soutaro (Soutaro Matsumoto)]

I believe the real question is "why #then defined in Kernel and not in Object"

It makes sense to me. Do we have a reason to keep them in Kernel not in Object?

[shevegen (Robert A. Heiler)]

Cons

The document of Object class will be almost empty, which may cause confusion for readers while there is
a link to included module, Kernel

It makes sense to me. Do we have a reason to keep them in Kernel not in Object?

I can not answer that - but personally I would prefer to keep it simple and show where it is defined
no matter what other explanations may exist. Personally I like a flat hierarchy so I concur.

I should however had also like to admit that I do not use "ri" personally. I ended up storing things
in my own local knowledge base and just end up googling for new information if I need it. But I can
see that the above is confusing for ruby users.

Perhaps the best would be to extend ri/rdoc to also allow "pointer" output on the commandline, such
as to display where a method is defined, and to then also show if there is another typical use
or definition.

Example what I mean, taking your input:

$ ri Kernel#then
Nothing known about Kernel#then
$ ri Object#then
[Prints documentation]

$ ri Kernel#then

"Kernel#then is available via Object#then. The documentation is as follows:"

[Prints documentation]

Just an example, e. g. display an additional line, and then show the documentation
for Object#then.

Would that solve the above issue? Of course that is just meant as an example;
there can be different solutions. If I understood your issue then the primary
problem is that in the first example you find no information at all, when in
reality the information is there - just with another name.

I guess "ri" was not that user-friendly when it was written back then.

So, in fact, I believe the real question is "why #then defined in Kernel and not in
Object" :)

I think this is only a secondary question, because while we can perhaps find some explanation
for that, the use case by soutaro is primarily about the general lack of "redirection" in
regards to ri/rdoc's usability, which I think is a fair point that he has raised. As to
where something effectively resides at, well - I guess in all these cases it will be that
the ruby user at hand would like to find anything useful. Better than to find nothing at
all, which I think soutaro may have to referred to ultimately. :)

[soutaro (Soutaro Matsumoto)]

I'd like to share the context. ri is not the true problem to me.

I'm working to import the RDoc documentation to RBS files. (https://github.com/ruby/ruby-signature/pull/84) I believe having documentations in RBS makes sense, at least for methods implemented in C.

RBS assumes it has the same module/class structure with Ruby code. In this case, #then should be defined in Kernel, not in Object. But the documentation cannot be retrieved through Kernel module. The problem is the inconsistency between the documentation (and users' expectation) and the implementation. #then is defined in Kernel, but document says it is in Object.

I'd like to propose one of the following:

1. Move the documentation of #then and others to Kernel (would drop because of comments here.)
2. Move the implementation of #then to Object (what is the reason blocking this?)
3. Admit inconsistency between the document and the implementation; RBS defines #then in Object, different from the implementation, consistent with the documentation.

I will try to uncover the reason for 2, or move to 3 if we found a good reason.

I'm not very sure if adding extra message for ri makes sense. It may help ri users, but I also feel the majority of developers are not using the tool.

[jeremyevans0 (Jeremy Evans)]

• Tracker changed from Bug to Feature
• Backport deleted (2.5: UNKNOWN, 2.6: UNKNOWN)

The current RDoc behavior is by design, so this isn't a bug, it's a feature request.

I agree it would be best for RDoc to reflect the reality that Kernel methods are defined in Kernel and not object, because if they were defined in Object, you could not override them in Object and call super to get the default behavior.

I'm against moving Kernel methods to object, because then you cannot override them in Object and call super to get the default behavior (this breaks backwards compatibility). You also wouldn't be able to do something like:

  class Foo < BasicObject
    include Kernel
  end

and get the methods.