[ruby-core:99357] [Ruby master Misc#17053] RDoc for Hash Keys

[marcandre-ruby-core@marc-andre.ca]

Issue #17053 has been updated by marcandre (Marc-Andre Lafortune).


Let me first repeat that I am very grateful of all efforts to improve our documentation.

Documentation can be difficult because it requires deep understanding of what needs to be documented and good experience with what is actually useful for users.



What I am referring to is that the documentation for, e.g `Hash#values_at`, currently reads as:

```
call-seq:
  hash.values_at(*keys) -> new_array
Returns a new \Array containing values for the given +keys+:
  h = {foo: 0, bar: 1, baz: 2}
  h.values_at(:foo, :baz) # => [0, 2]
Returns an empty Array if no arguments given:
  h = {foo: 0, bar: 1, baz: 2}
  h.values_at # => []
---
Raises an exception if any given key is invalid
(see {Invalid Hash Keys}[#class-Hash-label-Invalid+Hash+Keys]):
  h = {foo: 0, bar: 1, baz: 2}
  # Raises NoMethodError (undefined method `hash' for #<BasicObject>):
```

There are 3 examples.

The first one is generic.

The second one is a corner case that is to me feels both obvious and not useful, but maybe it isn't for everybody. I didn't even try suggesting to remove it, although I see little value in it.

What I've asked @burnettelamar to do was to remove the last example and simply refer to the top-level documentation for invalid keys, because that example feels to me as a burden on the reader that is not helpful.

Moreover, the sentence "Raises an exception if any given key is invalid" is not even accurate:

```ruby
# empty hash case
{}.values_at(BasicObject.new) # => [nil]
# or
h = {a: 1, b: 2}
h.compare_by_identity
h.values_at(BasicObject.new) # => [nil]
```

The invalid key section seems to imply that keys need to implement `hash`, which also is inaccurate as implementing `eql?` is also mandatory.

Even if it was accurate, my feeling is that trying to use invalid keys in a hash is not a concern and should not be addressed repeatedly with examples for `values_at`, `slice`, etc.

My experience is that very very few Rubyists use `BasicObject` or objects that do not define `eql?` and `hash`.


Finally, the current documentation gives no example of `values_at` with a key that isn't found, and doesn't even state that the `defaut`/`default_proc` is used in those cases, which I believe to be useful.

I am surprised that the above, once pointed out, isn't clear.


----------------------------------------
Misc #17053: RDoc for Hash Keys
https://bugs.ruby-lang.org/issues/17053#change-86757

* Author: burdettelamar@yahoo.com (Burdette Lamar)
* Status: Open
* Priority: Normal
----------------------------------------
@marcandre writes, about the  Hash Rdoc at https://docs.ruby-lang.org/en/master/Hash.html#class-Hash-label-Hash+Keys :

> The only thing I would change is that I would shorten the doc on the "Invalid Hash Keys". As far as I know, this is simply not a important concern as nearly all Ruby objects respond_to? :hash and :eql?

> I personally would recommend adding a single example in the Hash.html#class-Hash-label-Hash+Keys section and I would remove the rest, or at least remove the examples. They burden the reader with something that is of no use to them.

I have misgivings:

* Some of this material is very old, like the text and example for user-defined hash keys.
* Some material I consolidated from earlier doc for individual methods, which now link to the relevant sections.
* All is factual, and not repeated elsewhere in the page.

My view has been this:  This is API reference documentation.  Ruby/ruby should have *the reference documentation*, and therefore should omit nothing.

If material such as this is to be included, I see three possibilities:
* Include in-line, as now.
* Link to on-page 'footnote', with Back link.
* Link to off-page rdoc, likely in doc/ dir.

I'd love to hear some opinions on this.




-- 
https://bugs.ruby-lang.org/