From: matsumoto@... Date: 2019-11-27T05:32:37+00:00 Subject: [ruby-core:95975] [Ruby master Bug#16373] RDoc for some of the Kernel methods cannot be found in Kernel module Issue #16373 has been updated by 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. ---------------------------------------- Bug #16373: RDoc for some of the Kernel methods cannot be found in Kernel module https://bugs.ruby-lang.org/issues/16373#change-82809 * Author: soutaro (Soutaro Matsumoto) * Status: Open * Priority: Normal * Assignee: * Target version: * ruby -v: * Backport: 2.5: UNKNOWN, 2.6: UNKNOWN ---------------------------------------- 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` -- https://bugs.ruby-lang.org/ Unsubscribe: