Project

General

Profile

Misc #17053

Updated by sawa (Tsuyoshi Sawada) about 2 months 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. 

Back