Hi Dave,
Fair enough, you don’t want to group aliases before their target, but
when I view the RDoc for a large module like FileUtils, it’s a bit
of a forest/trees scenario. The basic problem is, the aliases aren’t
important enough to justify the amount of screen real-estate they
occupy, and the fact that they are presented just like methods makes
it difficult to subconciously locate the important information on the
screen.
Therefore, I think aliases should be presented along these lines:
- method name distinguished: grey and italic or something
- target of alias on the same line as method name
- an arrow or something instead of text (“Alias for”)
Cheers,
Gavin
It seems that once per N months, I am bound to send something to -talk
that I didn’t intend to. Call it momentum. Please excuse 
···
On Monday, January 27, 2003, 7:33:11 PM, Gavin wrote:
Hi Dave, […]
Gavin Sinclair gsinclair@soyabean.com.au writes:
when I view the RDoc for a large module like FileUtils, it’s a bit
of a forest/trees scenario.
Yes I’ve been thinking about an RDoc feature that allows the
programmer to organize the method list into functional groups.
E.g. I now have a class with 60 methods, but they divide up into nice
groups of functionality. The RDoc output is currently a flat list of
methods so this structure is not immediately evident to the reader and
the class appears more complex than it really is.
This would solve the ‘alias’ problem too, since you could put all the
aliases at the end under a “method aliases” section.
Gavin Sinclair gsinclair@soyabean.com.au writes:
when I view the RDoc for a large module like FileUtils, it’s a bit
of a forest/trees scenario.
Yes I’ve been thinking about an RDoc feature that allows the
programmer to organize the method list into functional groups.
E.g. I now have a class with 60 methods, but they divide up into nice
groups of functionality. The RDoc output is currently a flat list of
methods so this structure is not immediately evident to the reader and
the class appears more complex than it really is.
Gavin Sinclair gsinclair@soyabean.com.au writes:
when I view the RDoc for a large module like FileUtils, it’s a bit
of a forest/trees scenario.
Yes I’ve been thinking about an RDoc feature that allows the
programmer to organize the method list into functional groups.
E.g. I now have a class with 60 methods, but they divide up into nice
groups of functionality. The RDoc output is currently a flat list of
methods so this structure is not immediately evident to the reader and
the class appears more complex than it really is.
Sounds like you want some more classes.
This would solve the ‘alias’ problem too, since you could put all the
aliases at the end under a “method aliases” section.
I don’t believe that grouping aliases is logical, because an alias is
logically the same as a method, and should be found as such. My
initial suggestion was for aliases to appear just before the target,
like in Ruby in a Nutshell. Dave rejected this because he wants to
maintain a different ordering - perhaps alphabetical.
Gavin
···
On Tuesday, January 28, 2003, 3:57:04 AM, Matt wrote: