https://bugs.ruby-lang.org/https://bugs.ruby-lang.org/favicon.ico?17113305112009-06-17T22:46:45ZRuby Issue Tracking SystemRuby master - Bug #1640: [PATCH] Documentation for the Rational Classhttps://bugs.ruby-lang.org/issues/1640?journal_id=43172009-06-17T22:46:45Ztadf (tadayoshi funaba)
<ul></ul><p>=begin<br>
thanks for your patch. i felt it is good on the whole.</p>
<p>i have some requests and hits.</p>
<p>should not use float on the description of divmod.<br>
divmod = div + modulo.<br>
div and modulo relate to floor, remainder relate to truncate.<br>
to_i is the alias of truncate.<br>
floor, ceil and truncate can accept an extra argument, not only round.</p>
<p>no need full explanation for regular method hash, i think.</p>
<p>Rational() can also accept float, string and rational.<br>
0.9, "1", "1/2", "0.3", "10e3", etc.<br>
to_r also, but never raise exception of parser error.</p>
<p>we never write:<br>
Integer("2") #=> Integer(2)</p>
<p>i like:<br>
Rational(1,2) #=> 1/2<br>
or<br>
Rational(1,2) #=> (1/2)</p>
<p>they are less distracting to read, i felt.</p>
<p>so, could you re-edit it?<br>
or i'll modify it if you don't mind.</p>
<p>=end</p> Ruby master - Bug #1640: [PATCH] Documentation for the Rational Classhttps://bugs.ruby-lang.org/issues/1640?journal_id=43192009-06-18T01:14:34Zrunpaint (Run Paint Run Run)runrun@runpaint.org
<ul><li><strong>File</strong> <a href="/attachments/419">rational.c-documentation.patch</a> <a class="icon-only icon-download" title="Download" href="/attachments/download/419/rational.c-documentation.patch">rational.c-documentation.patch</a> added</li></ul><p>=begin</p>
<blockquote>
<p>should not use float on the description of divmod.<br>
divmod = div + modulo.</p>
</blockquote>
<p>I've removed that explanation.</p>
<blockquote>
<p>div and modulo relate to floor, remainder relate to truncate.</p>
</blockquote>
<p>Do you suggest a "see also" pointer between these methods, or did you want something else?</p>
<blockquote>
<p>to_i is the alias of truncate.</p>
</blockquote>
<p>I documented them separately because #truncate takes an argument, and #to_i doesn't. Plus, because they use different function names I don't know how to tell rdoc to use the same description for different functions.</p>
<blockquote>
<p>floor, ceil and truncate can accept an extra argument, not only round.</p>
</blockquote>
<p>Yes, I realised that. I didn't document them because I was waiting for an explanation of how that argument worked. Could you explain it to me? :-)</p>
<blockquote>
<p>no need full explanation for regular method hash, i think.</p>
</blockquote>
<p>I've removed that comment.</p>
<blockquote>
<p>Rational() can also accept float, string and rational.<br>
0.9, "1", "1/2", "0.3", "10e3", etc.</p>
</blockquote>
<p>I've clarified that in the preamble.</p>
<blockquote>
<p>to_r also, but never raise exception of parser error.</p>
</blockquote>
<p>I don't understand this. Rational() doesn't call #to_r on arguments, and does raise errors for invalid arguments. Could you clarify?</p>
<blockquote>
<p>we never write:<br>
Integer("2") #=> Integer(2)</p>
<p>i like:<br>
Rational(1,2) #=> 1/2<br>
or<br>
Rational(1,2) #=> (1/2)</p>
</blockquote>
<p>I've changed them all to use the latter style.</p>
<p>Thanks for your review. :-) I've attached an updated patch.<br>
=end</p> Ruby master - Bug #1640: [PATCH] Documentation for the Rational Classhttps://bugs.ruby-lang.org/issues/1640?journal_id=43222009-06-18T07:43:39Ztadf (tadayoshi funaba)
<ul></ul><p>=begin</p>
<blockquote>
<blockquote>
<p>div and modulo relate to floor, remainder relate to truncate.</p>
</blockquote>
<p>Do you suggest a "see also" pointer between these methods, or did you want something else?</p>
</blockquote>
<p>i think many programmer don't understand differences between modulo<br>
and remainder.</p>
<p>"If <em>rat</em> and <em>numeric</em> have different signs, returns <em>mod</em>-<em>numeric</em>..."<br>
it's so difficult for me.</p>
<p>x modulo y = x-y<em>floor(x/y)<br>
x remainder y = x-y</em>truncate(x/y)</p>
<p>x = Rational(13); y = Rational(-4)<br>
x-y*(x/y).floor #=> (-3/1)<br>
x-y*(x/y).truncate #=> (1/1)</p>
<p>x.modulo(y) #=> (-3/1)<br>
x.remainder(y) #=> (1/1)</p>
<p>and</p>
<p>x-y*(x/y).div(1)#=> (-3/1) # modulo</p>
<blockquote>
<blockquote>
<p>floor, ceil and truncate can accept an extra argument, not only round.</p>
</blockquote>
<p>Yes, I realised that. I didn't document them because I was waiting for an explanation of how that argument worked. Could you explain it to me? :-)</p>
</blockquote>
<p>same.<br>
floor (-inf), ceil (+inf), truncate (zero) and round (nearest)</p>
<p>'%f' % Rational('-1.125').floor(2) #=> "-1.130000"<br>
'%f' % Rational('-1.125').ceil(2) #=> "-1.120000"<br>
'%f' % Rational('-1.125').truncate(2) #=> "-1.120000"<br>
'%f' % Rational('-1.125').round(2) #=> "-1.130000"</p>
<p>'%f'% ((Rational('-1.125')<em>10**2).floor</em>10**-2) #=> "-1.130000"<br>
'%f'% ((Rational('-1.125')<em>10**2).ceil</em>10**-2) #=> "-1.120000"<br>
'%f'% ((Rational('-1.125')<em>10**2).truncate</em>10**-2) #=> "-1.120000"<br>
'%f'% ((Rational('-1.125')<em>10**2).round</em>10**-2) #=> "-1.130000"</p>
<p>also accept negative number.</p>
<p>'%f' % Rational('12345.6789').round(2) #=> "12345.680000"<br>
'%f' % Rational('12345.6789').round(-2) #=> "12300.000000"</p>
<p>see also Float#round.</p>
<p>12345.6789.round(2) #=> 12345.68<br>
12345.6789.round(-2) #=> 12300</p>
<blockquote>
<blockquote>
<p>to_r also, but never raise exception of parser error.</p>
</blockquote>
<p>I don't understand this. Rational() doesn't call #to_r on arguments, and does raise errors for invalid arguments. Could you clarify?</p>
</blockquote>
<p>it's ruby's style.</p>
<p>$ ruby -e 'p Integer("x")'<br>
-e:1:in `Integer': invalid value for Integer: "x" (ArgumentError)<br>
from -e:1</p>
<p>$ ruby -e 'p Integer(nil)'<br>
-e:1:in <code>Integer': can't convert nil into Integer (TypeError) from -e:1:in </code>'</p>
<p>$ ruby -e 'p Integer(Integer(Integer("0")))'<br>
0</p>
<p>$ ruby -e 'p "x".to_i'<br>
0</p>
<p>Thanks for your re-edit.</p>
<p>=end</p> Ruby master - Bug #1640: [PATCH] Documentation for the Rational Classhttps://bugs.ruby-lang.org/issues/1640?journal_id=43232009-06-18T10:11:01Zrunpaint (Run Paint Run Run)runrun@runpaint.org
<ul><li><strong>File</strong> <a href="/attachments/420">rational.c-documentation.patch</a> <a class="icon-only icon-download" title="Download" href="/attachments/download/420/rational.c-documentation.patch">rational.c-documentation.patch</a> added</li></ul><p>=begin<br>
Thanks, Tadayoshi. I've, hopefully, incorporated your suggestions in the attached patch.<br>
=end</p> Ruby master - Bug #1640: [PATCH] Documentation for the Rational Classhttps://bugs.ruby-lang.org/issues/1640?journal_id=43252009-06-18T20:55:12Ztadf (tadayoshi funaba)
<ul></ul><p>=begin<br>
i'm not good at english.<br>
however, the patch's descriptions are very similar to the book's reference of<br>
"Programming Ruby" by Thomas & Hunt.<br>
especially, deleted divmod, deleted hash and remiander.</p>
<p>i'm not sure whether this is no problem or not.</p>
<p><a href="http://www.rubycentral.com/pickaxe/ref_c_numeric.html#Numeric.divmod" class="external">http://www.rubycentral.com/pickaxe/ref_c_numeric.html#Numeric.divmod</a><br>
<a href="http://www.rubycentral.com/pickaxe/ref_c_object.html#Object.hash" class="external">http://www.rubycentral.com/pickaxe/ref_c_object.html#Object.hash</a><br>
<a href="http://www.rubycentral.com/pickaxe/ref_c_numeric.html#Numeric.remainder" class="external">http://www.rubycentral.com/pickaxe/ref_c_numeric.html#Numeric.remainder</a></p>
<p>initial patch:<br>
<a href="http://redmine.ruby-lang.org/attachments/download/417" class="external">http://redmine.ruby-lang.org/attachments/download/417</a></p>
<p>=end</p> Ruby master - Bug #1640: [PATCH] Documentation for the Rational Classhttps://bugs.ruby-lang.org/issues/1640?journal_id=43282009-06-19T08:20:48Zrunpaint (Run Paint Run Run)runrun@runpaint.org
<ul></ul><p>=begin</p>
<blockquote>
<p>i'm not good at english.<br>
however, the patch's descriptions are very similar to the book's reference of<br>
"Programming Ruby" by Thomas & Hunt.<br>
especially, deleted divmod, deleted hash and remiander.</p>
<p>i'm not sure whether this is no problem or not.</p>
</blockquote>
<p>It's not a problem. They were based on the existing rdoc for those<br>
methods, which was in turn legally derived from that book. For<br>
example, <code>ri Numeric#divmod</code> cf.<br>
<a href="http://www.rubycentral.com/pickaxe/ref_c_numeric.html#Numeric.divmod" class="external">http://www.rubycentral.com/pickaxe/ref_c_numeric.html#Numeric.divmod</a> .</p>
<p>--<br>
Run Paint Run Run</p>
<p>=end</p> Ruby master - Bug #1640: [PATCH] Documentation for the Rational Classhttps://bugs.ruby-lang.org/issues/1640?journal_id=43292009-06-19T09:16:35Ztadf (tadayoshi funaba)
<ul></ul><p>=begin<br>
ok, i understand.<br>
i didn't notice it due to focus the text.<br>
i think i should have reviewed rdocs numeric and others.<br>
and i think we don't need copy & paste text.</p>
<p>=end</p> Ruby master - Bug #1640: [PATCH] Documentation for the Rational Classhttps://bugs.ruby-lang.org/issues/1640?journal_id=43302009-06-19T09:43:03Zrunpaint (Run Paint Run Run)runrun@runpaint.org
<ul></ul><p>=begin</p>
<blockquote>
<p>ok, i understand.<br>
i didn't notice it due to focus the text.<br>
i think i should have reviewed rdocs numeric and others.<br>
and i think we don't need copy & paste text.</p>
</blockquote>
<p>As you noted, the few descriptions that were derived from other rdoc<br>
have either been since removed or heavily edited. Given the way rdoc<br>
works, some text duplication is necessary to ensure that all methods<br>
have descriptions. It's singularly unhelpful, for example, to remove<br>
the documentation for Rational#divmod on the basis that Numeric#divmod<br>
is similar. This requires the potential user of Rational#divmod to<br>
execute <code>ri Rational#divmod</code>, be informed that "Nothing [is] known<br>
about Rational#divmod", execute <code>ri Rational</code>and find nothing there,<br>
then, hopefully, guess that Rational inherits from Numeric, despite<br>
the rdoc not mentioning this, then execute <code>ri Numeric#divmod</code>, and<br>
translate between the examples.</p>
<p>What are you suggesting?</p>
<p>--<br>
Run Paint Run Run</p>
<p>=end</p> Ruby master - Bug #1640: [PATCH] Documentation for the Rational Classhttps://bugs.ruby-lang.org/issues/1640?journal_id=43312009-06-19T10:04:32Zdrbrain (Eric Hodel)drbrain@segment7.net
<ul></ul><p>=begin<br>
On Jun 18, 2009, at 17:42, Run Paint Run Run wrote:</p>
<blockquote>
<blockquote>
<p>ok, i understand.<br>
i didn't notice it due to focus the text.<br>
i think i should have reviewed rdocs numeric and others.<br>
and i think we don't need copy & paste text.</p>
</blockquote>
<p>As you noted, the few descriptions that were derived from other rdoc<br>
have either been since removed or heavily edited. Given the way rdoc<br>
works, some text duplication is necessary to ensure that all methods<br>
have descriptions. It's singularly unhelpful, for example, to remove<br>
the documentation for Rational#divmod on the basis that Numeric#divmod<br>
is similar. This requires the potential user of Rational#divmod to<br>
execute <code>ri Rational#divmod</code>, be informed that "Nothing [is] known<br>
about Rational#divmod", execute <code>ri Rational</code>and find nothing there,<br>
then, hopefully, guess that Rational inherits from Numeric, despite<br>
the rdoc not mentioning this, then execute <code>ri Numeric#divmod</code>, and<br>
translate between the examples.</p>
</blockquote>
<p>RDoc expects that a method that is defined has documentation. At this<br>
point Rational#divmod should at least have a comment saying "see<br>
Numeric#divmod".</p>
<p>RDoc 2's ri will walk the ancestors looking for documentation, but<br>
that won't help for this case as Rational#divmod is "in the way".</p>
<p>I could improve RDoc with some directives to help for cases like<br>
these, but it may be difficult to implement. RDoc doesn't necessarily<br>
see files in order. If Rational#divmod had a directive that said "see<br>
Numeric#divmod" RDoc might not yet have comments from Numeric to hook<br>
the two up.</p>
<p>=end</p> Ruby master - Bug #1640: [PATCH] Documentation for the Rational Classhttps://bugs.ruby-lang.org/issues/1640?journal_id=43382009-06-19T20:29:51Ztadf (tadayoshi funaba)
<ul></ul><p>=begin<br>
i'll merge it.<br>
and i'll try to adjust some rdocs numeric and others.<br>
thanks for your effort.</p>
<p>=end</p> Ruby master - Bug #1640: [PATCH] Documentation for the Rational Classhttps://bugs.ruby-lang.org/issues/1640?journal_id=46122009-07-13T21:53:33Zyugui (Yuki Sonoda)yugui@yugui.jp
<ul><li><strong>Assignee</strong> set to <i>tadf (tadayoshi funaba)</i></li><li><strong>Priority</strong> changed from <i>Normal</i> to <i>3</i></li><li><strong>Target version</strong> set to <i>1.9.2</i></li></ul><p>=begin</p>
<p>=end</p> Ruby master - Bug #1640: [PATCH] Documentation for the Rational Classhttps://bugs.ruby-lang.org/issues/1640?journal_id=48782009-07-19T23:29:48Ztadf (tadayoshi funaba)
<ul><li><strong>Status</strong> changed from <i>Open</i> to <i>Closed</i></li></ul><p>=begin<br>
not a bug.<br>
=end</p>