Bug #1640: [PATCH] Documentation for the Rational Class

• Status: Closed
• Assignee: tadf (tadayoshi funaba)
• Target version: 1.9.2
• ruby -v: ruby 1.9.2dev (2009-06-14 trunk 23691) [i686-linux]

[runpaint (Run Paint Run Run)]

=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

[tadf (tadayoshi funaba)]

=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

[runpaint (Run Paint Run Run)]

• File rational.c-documentation.patch rational.c-documentation.patch added

=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

[tadf (tadayoshi funaba)]

=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

[runpaint (Run Paint Run Run)]

• File rational.c-documentation.patch rational.c-documentation.patch added

=begin
Thanks, Tadayoshi. I've, hopefully, incorporated your suggestions in the attached patch.
=end

[tadf (tadayoshi funaba)]

=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

[runpaint (Run Paint Run Run)]

=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

[tadf (tadayoshi funaba)]

=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

[runpaint (Run Paint Run Run)]

=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 Rationaland 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

[drbrain (Eric Hodel)]

=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
execute ri Rational#divmod, be informed that "Nothing [is] known
about Rational#divmod", execute ri Rationaland 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.

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

[tadf (tadayoshi funaba)]

=begin
i'll merge it.
and i'll try to adjust some rdocs numeric and others.
thanks for your effort.

=end

[yugui (Yuki Sonoda)]

• Assignee set to tadf (tadayoshi funaba)
• Priority changed from Normal to 3
• Target version set to 1.9.2

=begin

=end

[tadf (tadayoshi funaba)]

• Status changed from Open to Closed

=begin
not a bug.
=end