Issue #19304 has been updated by austin (Austin Ziegler). I think that (2) looks promising if sections are used (https://ruby.github.io/rdoc/RDoc/Markup.html#class-RDoc::Markup-label-Sectio...) in the documentation, although I must admit that I’ve never used those. It would absolutely need to be used consistently in both C and `kernel.rb` method definitions. ---------------------------------------- Misc #19304: Kernel vs Object documentation https://bugs.ruby-lang.org/issues/19304#change-100975 * 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/