Project

General

Profile

Bug #1640

[PATCH] Documentation for the Rational Class

Added by runpaint (Run Paint Run Run) over 11 years ago. Updated over 9 years ago.

Status:
Closed
Priority:
Normal
Target version:
ruby -v:
ruby 1.9.2dev (2009-06-14 trunk 23691) [i686-linux]
Backport:
[ruby-core:23869]

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
#1

Updated by tadf (tadayoshi funaba) over 11 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

#2

Updated by runpaint (Run Paint Run Run) over 11 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

#3

Updated by tadf (tadayoshi funaba) over 11 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-y*floor(x/y)
x remainder y = x-y*truncate(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')102).floor*10-2) #=> "-1.130000"
'%f'% ((Rational('-1.125')*10
2).ceil*10-2) #=> "-1.120000"
'%f'% ((Rational('-1.125')*10
2).truncate*10-2) #=> "-1.120000"
'%f'% ((Rational('-1.125')*10
2).round*10*-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

#4

Updated by runpaint (Run Paint Run Run) over 11 years ago

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

#5

Updated by tadf (tadayoshi funaba) over 11 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

#6

Updated by runpaint (Run Paint Run Run) over 11 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

#7

Updated by tadf (tadayoshi funaba) over 11 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

#8

Updated by runpaint (Run Paint Run Run) over 11 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 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

#9

Updated by drbrain (Eric Hodel) over 11 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
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

#10

Updated by tadf (tadayoshi funaba) over 11 years ago

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

=end

#11

Updated by yugui (Yuki Sonoda) over 11 years ago

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

=begin

=end

#12

Updated by tadf (tadayoshi funaba) over 11 years ago

  • Status changed from Open to Closed

=begin
not a bug.
=end

Also available in: Atom PDF