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

Issue #19304 has been updated by mame (Yusuke Endoh).


Discussed at the dev meeting. In conclusion, Option 4 looks good.

* Stop that "hack" of RDoc; all methods defined in Kernel should be listed in the Kernel documentation.
* rdoc should clearly distinguish between module functions and others. (This is not limited to Kernel)
* It is okay to state, at the beginning of the Kernel documentation, that Kernel's module functions are a global function in effect.

The current RDoc does not appear to handle module functions correctly. For example, `Math.acos` is listed as "Public Class Methods", which would not be appropriate. If this is fixed, the problem of this ticket should be also fixed automatically, we thought.

For the record, matz stated that he does not feel the need to distinguish between global functions (e.g., fork and exit) and others (e.g., is_a? and kind_of?), either in the implementation or in the documentation. He is fine with all methods being presented in one list. But he was not opposed to the above handling.

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

* 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/