Project

General

Profile

Misc #17053

RDoc for Hash Keys

Added by burdettelamar@yahoo.com (Burdette Lamar) about 2 months ago. Updated about 2 months ago.

Status:
Open
Priority:
Normal
Assignee:
-
[ruby-core:99354]

Description

marcandre comments on my pull request regarding documentation of Hash in Rdoc:

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] 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:

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

This is an API reference documentation. Ruby should have a reference documentation, and therefore should not omit anything.

If such material is to be included, I see three possibilities:

  • Include inline, as is now.
  • Link to a footnote on the same page, with a back link.
  • Link to another rdoc page in doc/ dir.

I'd love to hear some opinions on this.

Also available in: Atom PDF