https://redmine.ruby-lang.org/https://redmine.ruby-lang.org/favicon.ico?17113305112020-12-03T20:24:32ZRuby Issue Tracking SystemRuby master - Bug #17364: Fix documentation for String#encode optionshttps://redmine.ruby-lang.org/issues/17364?journal_id=889092020-12-03T20:24:32Zjeremyevans0 (Jeremy Evans)merch-redmine@jeremyevans.net
<ul></ul><p>Which format should be used in documentation depends on the method implementation. If the method ignores unrecognized keywords, then <code>**options</code> should be used. If the method raises an ArgumentError for unrecognized keywords, then keywords should be listed explicitly. This is to mirror how the method would work if implemented in Ruby.</p>
<p>In this case, <code>String#encode</code> ignores unrecognized keywords, so the <code>**options</code> approach is preferable:</p>
<pre><code class="ruby syntaxhl" data-language="ruby"><span class="s2">"a"</span><span class="p">.</span><span class="nf">encode</span><span class="p">(</span><span class="s1">'UTF-8'</span><span class="p">,</span> <span class="ss">:foo</span><span class="o">=></span><span class="ss">:bar</span><span class="p">)</span>
<span class="c1"># => "a"</span>
</code></pre>
<p>Note that you should use <code>str.encode(encoding, **options)</code>, (no <code>[]</code> around options), because a keyword splat is always optional. Personally, I don't think we should use <code>[]</code> around optional arguments in call-seq, we should use a default value for the argument or separate call-seq line. That is the approach recommended by the method documentation guide (doc/method_documentation.rdoc).</p> Ruby master - Bug #17364: Fix documentation for String#encode optionshttps://redmine.ruby-lang.org/issues/17364?journal_id=889102020-12-03T20:39:26Ztjschuck (T.J. Schuck)tj@tjschuck.com
<ul><li><strong>File</strong> <a href="/attachments/8621">string_encode_docs.diff</a> <a class="icon-only icon-download" title="Download" href="/attachments/download/8621/string_encode_docs.diff">string_encode_docs.diff</a> added</li></ul><p>Aha, thanks for the pointer to <code>doc/method_documentation.rdoc</code>, Jeremy — very helpful!</p>
<p>Based on the info you provided, it seems like using <code>**options</code> and axing the <code>[]</code> in the call-seq is the preferred method. The attached diff should be the "final" state, then. Should I open a PR on GitHub since this is a "minor" change, submit a patch here, or just leave the diff below?</p>
<p>(It would also be ideal if this could be backported to 2.7 to save anyone else hitting the warning from taking the journey I did to get here.)</p> Ruby master - Bug #17364: Fix documentation for String#encode optionshttps://redmine.ruby-lang.org/issues/17364?journal_id=889112020-12-03T20:46:38Zjeremyevans0 (Jeremy Evans)merch-redmine@jeremyevans.net
<ul><li><strong>Backport</strong> changed from <i>2.5: UNKNOWN, 2.6: UNKNOWN, 2.7: UNKNOWN</i> to <i>2.5: UNKNOWN, 2.6: UNKNOWN, 2.7: REQUIRED</i></li></ul><p>tjschuck (T.J. Schuck) wrote in <a href="#note-2">#note-2</a>:</p>
<blockquote>
<p>Aha, thanks for the pointer to <code>doc/method_documentation.rdoc</code>, Jeremy — very helpful!</p>
<p>Based on the info you provided, it seems like using <code>**options</code> and axing the <code>[]</code> in the call-seq is the preferred method. The attached diff should be the "final" state, then. Should I open a PR on GitHub since this is a "minor" change, submit a patch here, or just leave the diff below?</p>
</blockquote>
<p>I can apply your patch.</p>
<blockquote>
<p>(It would also be ideal if this could be backported to 2.7 to save anyone else hitting the warning from taking the journey I did to get here.)</p>
</blockquote>
<p>Since you requested this, I'll mark this for backporting. I do not think it is worth it from a cost/benefit perspective to backport documentation patches, but whether to do so is up to branch maintainer.</p> Ruby master - Bug #17364: Fix documentation for String#encode optionshttps://redmine.ruby-lang.org/issues/17364?journal_id=889122020-12-03T20:51:41Ztjschuck (T.J. Schuck)tj@tjschuck.com
<ul></ul><p>Thank you, Jeremy — I appreciate all the assistance you gave here!</p> Ruby master - Bug #17364: Fix documentation for String#encode optionshttps://redmine.ruby-lang.org/issues/17364?journal_id=889132020-12-03T21:08:06Zjeremyevans (Jeremy Evans)code@jeremyevans.net
<ul><li><strong>Status</strong> changed from <i>Open</i> to <i>Closed</i></li></ul><p>Applied in changeset <a class="changeset" title="Update documentation for String#encode{,!} [ci skip] These methods take keywords, not a hash. F..." href="https://redmine.ruby-lang.org/projects/ruby-master/repository/git/revisions/9195310168fa43186b1918fb0432a54b000fcbba">git|9195310168fa43186b1918fb0432a54b000fcbba</a>.</p>
<hr>
<p>Update documentation for String#encode{,!} [ci skip]</p>
<p>These methods take keywords, not a hash.</p>
<p>From tjschuck (T.J. Schuck)</p>
<p>Fixes [Bug <a class="issue tracker-1 status-5 priority-4 priority-default closed" title="Bug: Fix documentation for String#encode options (Closed)" href="https://redmine.ruby-lang.org/issues/17364">#17364</a>]</p>