From: burdettelamar@... Date: 2020-07-27T15:42:51+00:00 Subject: [ruby-core:99354] [Ruby master Bug#17053] RDoc for Hash Keys Issue #17053 has been reported by burdettelamar@yahoo.com (Burdette Lamar). ---------------------------------------- Bug #17053: RDoc for Hash Keys https://bugs.ruby-lang.org/issues/17053 * Author: burdettelamar@yahoo.com (Burdette Lamar) * Status: Open * Priority: Normal * ruby -v: ruby 2.7.0p0 (2019-12-25 revision 647ee6f091) [x64-mingw32] * Backport: 2.5: UNKNOWN, 2.6: UNKNOWN, 2.7: UNKNOWN ---------------------------------------- @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: