[ruby-core:111613] [Ruby master Misc#19304] Kernel vs Object documentation

Issue #19304 has been updated by nobu (Nobuyoshi Nakada).


Is the option 3 like this?
https://github.com/ruby/rdoc/pull/961

----------------------------------------
Misc #19304: Kernel vs Object documentation
https://bugs.ruby-lang.org/issues/19304#change-100985

* 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/lib/rdoc/parser/c.rb#L477) 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/
 ______________________________________________
 ruby-core mailing list -- [e-mail]
 To unsubscribe send an email to [e-mail]
 ruby-core info -- https://ml.ruby-lang.org/mailman3/postorius/lists/ruby-core.ml.ruby-lang.org/