Misc #17053
Updated by sawa (Tsuyoshi Sawada) over 4 years ago
marcandre [comments](https://github.com/ruby/ruby/pull/3139#issuecomment-663281047) on my pull request regarding [documentation of @marcandre writes, about the Hash in Rdoc](https://docs.ruby-lang.org/en/master/Hash.html#class-Hash-label-Hash+Keys): 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[n] 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 about it: misgivings: * Some of this material is very old, like the material, for example, the text and example for user-defined hash keys, is very old. keys. * Some material I consolidated some material from earlier doc for individual methods, which now link to the relevant sections. * All are factual is factual, and not repeated elsewhere in the page. My view has been this: This is an API reference documentation. Ruby Ruby/ruby should have a *reference *the reference documentation*, and therefore should not omit anything. nothing. If material such material as this is to be included, I see three possibilities: * Include inline, in-line, as is now. * Link to a footnote on the same page, on-page 'footnote', with a back Back link. * Link to another rdoc page off-page rdoc, likely in `doc/` doc/ dir. I'd love to hear some opinions on this.