From: burdettelamar@...
Date: 2020-07-27T17:55:03+00:00
Subject: [ruby-core:99356] [Ruby master Misc#17053] RDoc for Hash Keys

Issue #17053 has been updated by burdettelamar@yahoo.com (Burdette Lamar).


Should have linked to the source of the remarks:  https://github.com/ruby/ruby/pull/3139#issuecomment-663281047

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

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

Unsubscribe: <mailto:ruby-core-request@ruby-lang.org?subject=unsubscribe>
<http://lists.ruby-lang.org/cgi-bin/mailman/options/ruby-core>