Bug #1640
closed[PATCH] Documentation for the Rational Class
Added by runpaint (Run Paint Run Run) about 15 years ago. Updated over 13 years ago.
Description
=begin
The Rational class has no documentation, so I've attached a first draft. Some comments:
- The class was defined with a constant name which caused the Rdoc C parser to ignore it. I've changed the constant to a literal string, but I assume there's a better approach.
- Some of the commented-out methods confused Rdoc. For instance, Rational#div had a commented-out alias of '//', which Rdoc displays. I didn't want to delete the commented-out code, so I'm not sure what to do about this. (I can't use :nodoc: for the function because it is used as #div).
- I didn't document the #marshal_* methods because other classes don't. Is this correct?
- I haven't documented the optional precision argument that some of the methods have because I wasn't sure I understood the algorithm enough to explain it. Any suggestions?
- The #coerce documentation assumes that bug #1636 will be fixed.
=end
Files
rational.c-documentation.patch (26.3 KB) rational.c-documentation.patch | runpaint (Run Paint Run Run), 06/16/2009 11:14 AM | ||
rational.c-documentation.patch (25 KB) rational.c-documentation.patch | runpaint (Run Paint Run Run), 06/18/2009 01:14 AM | ||
rational.c-documentation.patch (27.5 KB) rational.c-documentation.patch | runpaint (Run Paint Run Run), 06/18/2009 10:11 AM |
Updated by tadf (tadayoshi funaba) about 15 years ago
=begin
thanks for your patch. i felt it is good on the whole.
i have some requests and hits.
should not use float on the description of divmod.
divmod = div + modulo.
div and modulo relate to floor, remainder relate to truncate.
to_i is the alias of truncate.
floor, ceil and truncate can accept an extra argument, not only round.
no need full explanation for regular method hash, i think.
Rational() can also accept float, string and rational.
0.9, "1", "1/2", "0.3", "10e3", etc.
to_r also, but never raise exception of parser error.
we never write:
Integer("2") #=> Integer(2)
i like:
Rational(1,2) #=> 1/2
or
Rational(1,2) #=> (1/2)
they are less distracting to read, i felt.
so, could you re-edit it?
or i'll modify it if you don't mind.
=end
Updated by runpaint (Run Paint Run Run) about 15 years ago
=begin
should not use float on the description of divmod.
divmod = div + modulo.
I've removed that explanation.
div and modulo relate to floor, remainder relate to truncate.
Do you suggest a "see also" pointer between these methods, or did you want something else?
to_i is the alias of truncate.
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.
floor, ceil and truncate can accept an extra argument, not only round.
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? :-)
no need full explanation for regular method hash, i think.
I've removed that comment.
Rational() can also accept float, string and rational.
0.9, "1", "1/2", "0.3", "10e3", etc.
I've clarified that in the preamble.
to_r also, but never raise exception of parser error.
I don't understand this. Rational() doesn't call #to_r on arguments, and does raise errors for invalid arguments. Could you clarify?
we never write:
Integer("2") #=> Integer(2)i like:
Rational(1,2) #=> 1/2
or
Rational(1,2) #=> (1/2)
I've changed them all to use the latter style.
Thanks for your review. :-) I've attached an updated patch.
=end
Updated by tadf (tadayoshi funaba) about 15 years ago
=begin
div and modulo relate to floor, remainder relate to truncate.
Do you suggest a "see also" pointer between these methods, or did you want something else?
i think many programmer don't understand differences between modulo
and remainder.
"If rat and numeric have different signs, returns mod-numeric..."
it's so difficult for me.
x modulo y = x-yfloor(x/y)
x remainder y = x-ytruncate(x/y)
x = Rational(13); y = Rational(-4)
x-y*(x/y).floor #=> (-3/1)
x-y*(x/y).truncate #=> (1/1)
x.modulo(y) #=> (-3/1)
x.remainder(y) #=> (1/1)
and
x-y*(x/y).div(1)#=> (-3/1) # modulo
floor, ceil and truncate can accept an extra argument, not only round.
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? :-)
same.
floor (-inf), ceil (+inf), truncate (zero) and round (nearest)
'%f' % Rational('-1.125').floor(2) #=> "-1.130000"
'%f' % Rational('-1.125').ceil(2) #=> "-1.120000"
'%f' % Rational('-1.125').truncate(2) #=> "-1.120000"
'%f' % Rational('-1.125').round(2) #=> "-1.130000"
'%f'% ((Rational('-1.125')10**2).floor10**-2) #=> "-1.130000"
'%f'% ((Rational('-1.125')10**2).ceil10**-2) #=> "-1.120000"
'%f'% ((Rational('-1.125')10**2).truncate10**-2) #=> "-1.120000"
'%f'% ((Rational('-1.125')10**2).round10**-2) #=> "-1.130000"
also accept negative number.
'%f' % Rational('12345.6789').round(2) #=> "12345.680000"
'%f' % Rational('12345.6789').round(-2) #=> "12300.000000"
see also Float#round.
12345.6789.round(2) #=> 12345.68
12345.6789.round(-2) #=> 12300
to_r also, but never raise exception of parser error.
I don't understand this. Rational() doesn't call #to_r on arguments, and does raise errors for invalid arguments. Could you clarify?
it's ruby's style.
$ ruby -e 'p Integer("x")'
-e:1:in `Integer': invalid value for Integer: "x" (ArgumentError)
from -e:1
$ ruby -e 'p Integer(nil)'
-e:1:in Integer': can't convert nil into Integer (TypeError) from -e:1:in
'
$ ruby -e 'p Integer(Integer(Integer("0")))'
0
$ ruby -e 'p "x".to_i'
0
Thanks for your re-edit.
=end
Updated by runpaint (Run Paint Run Run) about 15 years ago
=begin
Thanks, Tadayoshi. I've, hopefully, incorporated your suggestions in the attached patch.
=end
Updated by tadf (tadayoshi funaba) about 15 years ago
=begin
i'm not good at english.
however, the patch's descriptions are very similar to the book's reference of
"Programming Ruby" by Thomas & Hunt.
especially, deleted divmod, deleted hash and remiander.
i'm not sure whether this is no problem or not.
http://www.rubycentral.com/pickaxe/ref_c_numeric.html#Numeric.divmod
http://www.rubycentral.com/pickaxe/ref_c_object.html#Object.hash
http://www.rubycentral.com/pickaxe/ref_c_numeric.html#Numeric.remainder
initial patch:
http://redmine.ruby-lang.org/attachments/download/417
=end
Updated by runpaint (Run Paint Run Run) about 15 years ago
=begin
i'm not good at english.
however, the patch's descriptions are very similar to the book's reference of
"Programming Ruby" by Thomas & Hunt.
especially, deleted divmod, deleted hash and remiander.i'm not sure whether this is no problem or not.
It's not a problem. They were based on the existing rdoc for those
methods, which was in turn legally derived from that book. For
example, ri Numeric#divmod
cf.
http://www.rubycentral.com/pickaxe/ref_c_numeric.html#Numeric.divmod .
--
Run Paint Run Run
=end
Updated by tadf (tadayoshi funaba) about 15 years ago
=begin
ok, i understand.
i didn't notice it due to focus the text.
i think i should have reviewed rdocs numeric and others.
and i think we don't need copy & paste text.
=end
Updated by runpaint (Run Paint Run Run) about 15 years ago
=begin
ok, i understand.
i didn't notice it due to focus the text.
i think i should have reviewed rdocs numeric and others.
and i think we don't need copy & paste text.
As you noted, the few descriptions that were derived from other rdoc
have either been since removed or heavily edited. Given the way rdoc
works, some text duplication is necessary to ensure that all methods
have descriptions. It's singularly unhelpful, for example, to remove
the documentation for Rational#divmod on the basis that Numeric#divmod
is similar. This requires the potential user of Rational#divmod to
execute ri Rational#divmod
, be informed that "Nothing [is] known
about Rational#divmod", execute ri Rational
and find nothing there,
then, hopefully, guess that Rational inherits from Numeric, despite
the rdoc not mentioning this, then execute ri Numeric#divmod
, and
translate between the examples.
What are you suggesting?
--
Run Paint Run Run
=end
Updated by drbrain (Eric Hodel) about 15 years ago
=begin
On Jun 18, 2009, at 17:42, Run Paint Run Run wrote:
ok, i understand.
i didn't notice it due to focus the text.
i think i should have reviewed rdocs numeric and others.
and i think we don't need copy & paste text.As you noted, the few descriptions that were derived from other rdoc
have either been since removed or heavily edited. Given the way rdoc
works, some text duplication is necessary to ensure that all methods
have descriptions. It's singularly unhelpful, for example, to remove
the documentation for Rational#divmod on the basis that Numeric#divmod
is similar. This requires the potential user of Rational#divmod to
executeri Rational#divmod
, be informed that "Nothing [is] known
about Rational#divmod", executeri Rational
and find nothing there,
then, hopefully, guess that Rational inherits from Numeric, despite
the rdoc not mentioning this, then executeri Numeric#divmod
, and
translate between the examples.
RDoc expects that a method that is defined has documentation. At this
point Rational#divmod should at least have a comment saying "see
Numeric#divmod".
RDoc 2's ri will walk the ancestors looking for documentation, but
that won't help for this case as Rational#divmod is "in the way".
I could improve RDoc with some directives to help for cases like
these, but it may be difficult to implement. RDoc doesn't necessarily
see files in order. If Rational#divmod had a directive that said "see
Numeric#divmod" RDoc might not yet have comments from Numeric to hook
the two up.
=end
Updated by tadf (tadayoshi funaba) about 15 years ago
=begin
i'll merge it.
and i'll try to adjust some rdocs numeric and others.
thanks for your effort.
=end
Updated by yugui (Yuki Sonoda) about 15 years ago
- Assignee set to tadf (tadayoshi funaba)
- Priority changed from Normal to 3
- Target version set to 1.9.2
=begin
=end
Updated by tadf (tadayoshi funaba) about 15 years ago
- Status changed from Open to Closed
=begin
not a bug.
=end