Issue #19304 has been updated by zverok (Victor Shepelev). @sawa
Can you expand on why option 2 would be super-confusing? I think that option is the best.
Because those are two different categories of methods (as this and the previous ticket discuss in detail), and having them in one mixed list makes it hard to distinguish "global methods" (aka Kernel's private) from "public methods that every object has". From every Ruby documentation user, it doesn't matter much that they are defined in the same module, but it _does_ matter much that methods like `puts` or `require` aren't homogenous with methods like `class`, `frozen?` or `clone`. That, I believe, was the reason for the initial RDoc decision to pretend public methods are belonging to `Object`. ---------------------------------------- Misc #19304: Kernel vs Object documentation https://bugs.ruby-lang.org/issues/19304#change-100994 * Author: zverok (Victor Shepelev) * Status: Open * Priority: Normal * Assignee: matz (Yukihiro Matsumoto) ---------------------------------------- The restating of the problems raised in #19300, from scratch. I believe it is rather a topic of **community significance** and would be happy if it is possible to **discuss on dev-meeting**, even if the outcome would probably "let's change RDoc in this or that way". So, the problem statement: 1. `Kernel` module defines two "types" of methods: private ones, that pretend to be global (like `puts`), but actually available from inside every object; and public ones (like `#class` or `#frozen?`) that are present in every object including `Kernel`. 2. Since the beginning of times, docs provided an illusion that the second type of the methods belongs to `Object` class, which is, in fact, devoid of its own definitions, just includes `Kernel`. This was handled by special RDoc hack (which, basically, forcefully [reattached definition](https://github.com/ruby/rdoc/blob/017bb9fa496ee0e0959facba694a053008d1ecb0/l...) of public methods if they are defined in `Kernel`, to `Object`) 3. The RDoc hack was working in C code only, so after introduction of `kernel.rb` the illusion started to crumble: methods like `#tap`, `#then`, `#class` [are now documented](https://docs.ruby-lang.org/en/3.2/Kernel.html) as belonging to `Kernel` (breaking the tradition of public methods being documented in `Object`) 4. This is all inconsistent and confusing, and I believe, adds to friction both for newcomers and curious investigators of the language! Additionally, I believe: 1. That the distinction of "two kinds of methods" is useful (saying from a practical experience with explaining Ruby while mentoring, writing articles, and discussing with colleagues) 2. But, considering everything, I agree with what @Eregon and @nobu say in #19300: pretending that methods belong not to the module they really belong to is not the optimal way to document things! So, the options I see (save for "do nothing and let things sort themselves somehow"): 1. Change Ruby's implementation so public methods would really belong to `Object`. Actually, I don't believe anybody would agree to experiment on this scale, so just listing it here for completeness. 2. Just remove the RDoc hack; all methods would belong to `Kernel`, and maybe some introductory free-form text will instruct that they are different. **Pro:** Easy to do. **Contra:** The `Kernel` docs would be super-confusing. 3. Continue to maintain the hack in RDoc and extend it to `kernel.rb` (so methods like `#clone` and `#frozen?` would be still in `Object`). **Pro:** Relatively easy to do, will maintain structure many people used to. **Contra:** This is still a lie, methods belong to `Kernel`, not `Object`. 4. Adjust RDoc to a) be able to separately list **public** and **private** methods in two different lists, and add intro for `Kernel` explaining how to treat those. **Pro:** Probably the best correspondence to reality? **Contra:** Not sure how easy it is to change RDoc this way; and other renderers (like ruby-doc.com and rubyapi.org) would need to adjust themselves. So far, (4) looks the most reasonable (if (1) is 100% impossible, that is!) -- https://bugs.ruby-lang.org/