Gavin Sinclair wrote:
[You may have seen this on -talk. I posted it there by misake. Sorry
about that. Here it is anyway.]
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”)
Ah - now I see what you’re thinking, and why there’s a disconnect.
As a programmer of a module, I agree: aliases are somewhat peripheral.
But I see RDoc as a tool for the user of a module. For these folks,
aliases are every bit as important as the original method. For example,
which is the alias, Enumerable#find_all or #select? I frankly couldn’t
tell you without looking it up, and from my perspective (as a user) I
don’t really care. Some folks will prefer one method name, some the
other, but both are used as if they were the method. For that reason I
believe aliases deserve equal billing in the RDoc output.
Cheers
Dave
“Equal billing” would mean that both names get the full documentation
underneath them. I completely agree that nobody cares which is the
alias and which is the method, but if aliases are going to be
documented, as they should, and they are going to be documentated as
aliases instead of methods, as they should, then it makes sense to
streamline their presentation just a little.
If the user wants to see the doco for Enumerable#select (the alias - I
had to look it up), all it will say is “Alias for find_all”. They
then have to click on it to see the real documentation. That’s the
way it is now, and I wouldn’t change it for the world. All I would
change is the presentation, slightly, so that the exact same
information doesn’t take up so much room. Just like attributes are
expressed in RDoc economically (even though they too are methods), I
think some economy of expression for aliases is sorely needed.
Anyway, I’m glad you see where I’m coming from. If you still
disagree, fine - I’ll find something else to bug you about instead 
Cheers,
Gavin
···
On Tuesday, January 28, 2003, 1:42:58 AM, Dave wrote:
Gavin Sinclair wrote:
[You may have seen this on -talk. I posted it there by misake. Sorry
about that. Here it is anyway.]
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”)
Ah - now I see what you’re thinking, and why there’s a disconnect.
As a programmer of a module, I agree: aliases are somewhat peripheral.
But I see RDoc as a tool for the user of a module. For these folks,
aliases are every bit as important as the original method. For example,
which is the alias, Enumerable#find_all or #select? I frankly couldn’t
tell you without looking it up, and from my perspective (as a user) I
don’t really care. Some folks will prefer one method name, some the
other, but both are used as if they were the method. For that reason I
believe aliases deserve equal billing in the RDoc output.