From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: X-Spam-Checker-Version: SpamAssassin 3.4.2 (2018-09-13) on dcvr.yhbt.net X-Spam-Level: X-Spam-Status: No, score=-2.5 required=3.0 tests=BAYES_00,DKIM_ADSP_CUSTOM_MED, FORGED_YAHOO_RCVD,FREEMAIL_FORGED_FROMDOMAIN,FREEMAIL_FROM, HEADER_FROM_DIFFERENT_DOMAINS,MAILING_LIST_MULTI,RCVD_IN_DNSWL_MED, SPF_HELO_NONE,SPF_PASS,UNPARSEABLE_RELAY shortcircuit=no autolearn=ham autolearn_force=no version=3.4.2 Received: from neon.ruby-lang.org (neon.ruby-lang.org [221.186.184.75]) by dcvr.yhbt.net (Postfix) with ESMTP id DCA981F5AE for ; Mon, 27 Jul 2020 15:43:06 +0000 (UTC) Received: from neon.ruby-lang.org (localhost [IPv6:::1]) by neon.ruby-lang.org (Postfix) with ESMTP id A7B23120959; Tue, 28 Jul 2020 00:42:27 +0900 (JST) Received: from xtrwkhkc.outbound-mail.sendgrid.net (xtrwkhkc.outbound-mail.sendgrid.net [167.89.16.28]) by neon.ruby-lang.org (Postfix) with ESMTPS id 74E34120933 for ; Tue, 28 Jul 2020 00:42:25 +0900 (JST) Received: by filterdrecv-p3iad2-5b55dcd864-m99xc with SMTP id filterdrecv-p3iad2-5b55dcd864-m99xc-18-5F1EF5FB-9 2020-07-27 15:42:51.088384177 +0000 UTC m=+2673205.693332442 Received: from herokuapp.com (unknown) by ismtpd0050p1iad1.sendgrid.net (SG) with ESMTP id JqKxz1F1Rbune35O7y7Kbg for ; Mon, 27 Jul 2020 15:42:50.953 +0000 (UTC) Date: Mon, 27 Jul 2020 15:42:51 +0000 (UTC) From: burdettelamar@yahoo.com Message-ID: References: Mime-Version: 1.0 X-Redmine-MailingListIntegration-Message-Ids: 75146 X-Redmine-Project: ruby-master X-Redmine-Issue-Tracker: Bug X-Redmine-Issue-Id: 17053 X-Redmine-Issue-Author: burdettelamar@yahoo.com X-Redmine-Sender: burdettelamar@yahoo.com X-Mailer: Redmine X-Redmine-Host: bugs.ruby-lang.org X-Redmine-Site: Ruby Issue Tracking System X-Auto-Response-Suppress: All Auto-Submitted: auto-generated X-SG-EID: =?us-ascii?Q?M0WX68AHQr=2FVSnvsB1Qo5xEo9+xKABJC=2FqJZ83MVt=2FqcrYxIc8T5ljBV+zz6em?= =?us-ascii?Q?8oJRC7udllC0MYhcSDcSHA0nhaPY=2FdXwd+tjCze?= =?us-ascii?Q?zLeiXLhcJcjsbVbYp5nKjCbHkD6bQj2A5KPMIBj?= =?us-ascii?Q?HcAUaDVrOymLlCDrOcQXgUqtmOKPDprLgp68zrO?= =?us-ascii?Q?v86J+WUEUWQZ954KIvp5iriIzo4XElOZhaWql69?= =?us-ascii?Q?g9zrZLZdMgERKDXdI=3D?= To: ruby-core@ruby-lang.org X-ML-Name: ruby-core X-Mail-Count: 99354 Subject: [ruby-core:99354] [Ruby master Bug#17053] RDoc for Hash Keys X-BeenThere: ruby-core@ruby-lang.org X-Mailman-Version: 2.1.15 Precedence: list Reply-To: Ruby developers List-Id: Ruby developers List-Unsubscribe: , List-Post: List-Help: List-Subscribe: , Content-Type: text/plain; charset="us-ascii" Content-Transfer-Encoding: 7bit Errors-To: ruby-core-bounces@ruby-lang.org Sender: "ruby-core" 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/