From: Eric Hodel <drbrain@...7.net>
Date: 2009-06-19T10:04:16+09:00
Subject: [ruby-core:23923] Re: [Bug #1640] [PATCH] Documentation for the  Rational Class

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 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.


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.