[ruby-core:95960] [Ruby master Bug#16373] RDoc for some of the Kernel methods cannot be found in Kernel module
From:
shevegen@...
Date:
2019-11-26 13:45:44 UTC
List:
ruby-core #95960
Issue #16373 has been updated by shevegen (Robert A. Heiler).
> 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
> It makes sense to me. Do we have a reason to keep them in Kernel not in Object?
I can not answer that - but personally I would prefer to keep it simple and show where it is defined
no matter what other explanations may exist. Personally I like a flat hierarchy so I concur.
I should however had also like to admit that I do not use "ri" personally. I ended up storing things
in my own local knowledge base and just end up googling for new information if I need it. But I can
see that the above is confusing for ruby users.
Perhaps the best would be to extend ri/rdoc to also allow "pointer" output on the commandline, such
as to display where a method is defined, and to then also show if there is another typical use
or definition.
Example what I mean, taking your input:
$ ri Kernel#then
Nothing known about Kernel#then
$ ri Object#then
[Prints documentation]
$ ri Kernel#then
"Kernel#then is available via Object#then. The documentation is as follows:"
[Prints documentation]
Just an example, e. g. display an additional line, and then show the documentation
for Object#then.
Would that solve the above issue? Of course that is just meant as an example;
there can be different solutions. If I understood your issue then the primary
problem is that in the first example you find no information at all, when in
reality the information is there - just with another name.
I guess "ri" was not that user-friendly when it was written back then.
----------------------------------------
Bug #16373: RDoc for some of the Kernel methods cannot be found in Kernel module
https://bugs.ruby-lang.org/issues/16373#change-82794
* 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: <mailto:[email protected]?subject=unsubscribe>
<http://lists.ruby-lang.org/cgi-bin/mailman/options/ruby-core>