https://bugs.ruby-lang.org/https://bugs.ruby-lang.org/favicon.ico?17113305112020-07-27T15:43:58ZRuby Issue Tracking SystemRuby master - Misc #17053: RDoc for Hash Keyshttps://bugs.ruby-lang.org/issues/17053?journal_id=867512020-07-27T15:43:58Zburdettelamar@yahoo.com (Burdette Lamar)burdettelamar@example.com
<ul><li><strong>Tracker</strong> changed from <i>Bug</i> to <i>Misc</i></li><li><strong>ruby -v</strong> deleted (<del><i>ruby 2.7.0p0 (2019-12-25 revision 647ee6f091) [x64-mingw32]</i></del>)</li><li><strong>Backport</strong> deleted (<del><i>2.5: UNKNOWN, 2.6: UNKNOWN, 2.7: UNKNOWN</i></del>)</li></ul> Ruby master - Misc #17053: RDoc for Hash Keyshttps://bugs.ruby-lang.org/issues/17053?journal_id=867522020-07-27T16:36:25Zsawa (Tsuyoshi Sawada)
<ul></ul><p>Where is the source of the quote? Neither of the links seems to lead to it.</p> Ruby master - Misc #17053: RDoc for Hash Keyshttps://bugs.ruby-lang.org/issues/17053?journal_id=867542020-07-27T17:55:03Zburdettelamar@yahoo.com (Burdette Lamar)burdettelamar@example.com
<ul></ul><p>Should have linked to the source of the remarks: <a href="https://github.com/ruby/ruby/pull/3139#issuecomment-663281047" class="external">https://github.com/ruby/ruby/pull/3139#issuecomment-663281047</a></p> Ruby master - Misc #17053: RDoc for Hash Keyshttps://bugs.ruby-lang.org/issues/17053?journal_id=867572020-07-27T18:37:16Zmarcandre (Marc-Andre Lafortune)marcandre-ruby-core@marc-andre.ca
<ul></ul><p>Let me first repeat that I am very grateful of all efforts to improve our documentation.</p>
<p>Documentation can be difficult because it requires deep understanding of what needs to be documented and good experience with what is actually useful for users.</p>
<p>What I am referring to is that the documentation for, e.g <code>Hash#values_at</code>, currently reads as:</p>
<pre><code>call-seq:
hash.values_at(*keys) -> new_array
Returns a new \Array containing values for the given +keys+:
h = {foo: 0, bar: 1, baz: 2}
h.values_at(:foo, :baz) # => [0, 2]
Returns an empty Array if no arguments given:
h = {foo: 0, bar: 1, baz: 2}
h.values_at # => []
---
Raises an exception if any given key is invalid
(see {Invalid Hash Keys}[#class-Hash-label-Invalid+Hash+Keys]):
h = {foo: 0, bar: 1, baz: 2}
# Raises NoMethodError (undefined method `hash' for #<BasicObject>):
</code></pre>
<p>There are 3 examples.</p>
<p>The first one is generic.</p>
<p>The second one is a corner case that is to me feels both obvious and not useful, but maybe it isn't for everybody. I didn't even try suggesting to remove it, although I see little value in it.</p>
<p>What I've asked @burnettelamar to do (or offered to do myself) was to remove the last example and simply refer to the top-level documentation for invalid keys, because that example feels to me as a burden on the reader that is not helpful.</p>
<p>Moreover, the sentence "Raises an exception if any given key is invalid" is not even accurate:</p>
<pre><code class="ruby syntaxhl" data-language="ruby"><span class="c1"># empty hash case</span>
<span class="p">{}.</span><span class="nf">values_at</span><span class="p">(</span><span class="no">BasicObject</span><span class="p">.</span><span class="nf">new</span><span class="p">)</span> <span class="c1"># => [nil]</span>
<span class="c1"># or</span>
<span class="n">h</span> <span class="o">=</span> <span class="p">{</span><span class="ss">a: </span><span class="mi">1</span><span class="p">,</span> <span class="ss">b: </span><span class="mi">2</span><span class="p">}</span>
<span class="n">h</span><span class="p">.</span><span class="nf">compare_by_identity</span>
<span class="n">h</span><span class="p">.</span><span class="nf">values_at</span><span class="p">(</span><span class="no">BasicObject</span><span class="p">.</span><span class="nf">new</span><span class="p">)</span> <span class="c1"># => [nil]</span>
</code></pre>
<p>The invalid key section seems to imply that keys need to implement <code>hash</code>, which also is inaccurate as implementing <code>eql?</code> is also mandatory.</p>
<p>Even if it was accurate, my feeling is that trying to use invalid keys in a hash is not a concern and should not be addressed repeatedly with examples for <code>values_at</code>, <code>slice</code>, etc.</p>
<p>My experience is that very very few Rubyists use <code>BasicObject</code> or objects that do not define <code>eql?</code> and <code>hash</code>.</p>
<p>Finally, the current documentation gives no example of <code>values_at</code> with a key that isn't found, and doesn't even state that the <code>defaut</code>/<code>default_proc</code> is used in those cases, which I believe to be useful.</p>
<p>I am surprised that the above, once pointed out, isn't clear.</p> Ruby master - Misc #17053: RDoc for Hash Keyshttps://bugs.ruby-lang.org/issues/17053?journal_id=867582020-07-27T19:22:48Zmarcandre (Marc-Andre Lafortune)marcandre-ruby-core@marc-andre.ca
<ul></ul><p><a href="mailto:burdettelamar@yahoo.com" class="email">burdettelamar@yahoo.com</a> (Burdette Lamar) wrote:</p>
<blockquote>
<p>My view has been this: This is API reference documentation. Ruby/ruby should have <em>the reference documentation</em>, and therefore should omit nothing.</p>
</blockquote>
<p>This is a very ambitious goal I'm not sure I share completely. Taking for example the documentation for <code>Hash</code>, one would need to talk about covariance of methods returning a hash (i.e. <code>Class.new(Hash).new.select{}.class</code> vs <code>Class.new(Hash).new.merge({}).class</code>), of treatment of a key <code>Float::NAN</code> (which is not <code>eql?</code> to itself), of recursive hashes, of the arity of enumerators (see <a href="https://bugs.ruby-lang.org/issues/14015#note-8" class="external">https://bugs.ruby-lang.org/issues/14015#note-8</a> ), of the performance of hash lookup / insertion...</p>
<p>All these details can not be repeated for each method, the same way we can't quote in full the floating point standard for <code>Float#+</code> and repeat it for <code>Float#-</code>, etc. On that subject, an example with <code>0.1 + 0.2</code> might be helpful though.</p> Ruby master - Misc #17053: RDoc for Hash Keyshttps://bugs.ruby-lang.org/issues/17053?journal_id=867602020-07-27T19:36:10Zburdettelamar@yahoo.com (Burdette Lamar)burdettelamar@example.com
<ul></ul><p>Thanks, <a class="user active user-mention" href="https://bugs.ruby-lang.org/users/182">@marcandre (Marc-Andre Lafortune)</a>. Your first update above makes things much clearer to me. I'll continue studying this.</p> Ruby master - Misc #17053: RDoc for Hash Keyshttps://bugs.ruby-lang.org/issues/17053?journal_id=867652020-07-28T01:21:30Zsawa (Tsuyoshi Sawada)
<ul><li><strong>Description</strong> updated (<a title="View differences" href="/journals/86765/diff?detail_id=57587">diff</a>)</li></ul>