> Disagreed. This has nothing to do with Ruby the language! RDoc is a
> tool that tries to parse the language statically. It is not part of the
> core of Ruby.
Having a conversation about whether the issue lies with RDOC or RUBY is
not the conversation I want to have. Because even if resolved ... even
if a judgement as to what's culpable was assigned with large agreement,
the issue remains unsolved.

As to implementation, perhaps RDOC could have been made better. I
concede that. Perhaps the right place to begin is the explicit
inclusion of includes, and requires statments in all API docs. At least
for ActionController::Base, one of the zillion Ruby classes out there,
it doesn't list includes and requires. Second, RDOC shoud process the
class_eval construction as in: ActionController::Base.class_eval do
... end. And third, perhaps RDOC should exhaustively process all files
under some root ``R". I write that because had RDOC processed

/usr/local/lib/ruby/gems/1.8/gems/actionpack-1.12.5/lib/action_controller.rb

perhaps the existing RDOC would have generated more complete API docs.
I'd have to check how the GEM RDOC generation is done to know whether
or not it even attempted to process this file. And finally, perhaps
RDOC should generate two lists: a list of modules and a list of classes
where the classes are show all their methods depending on their super
classes and modules where included.

But on the other hand, implementation was always going to be a
fundamental challenge precisely because Ruby isn't a static language as
you write. Indeed, because of the PERL like flexibility in
the syntax and the number of ways modules and classes can be expanded
--- all issues about
the language itself --- it'd be a real challenge to get a good RDOC
implementation running. By and large, these aren't the issues you'd run
into with Eiffel/Java/C++ precisely because they're static. Eiffel, in
particular, goes out of its way to have a minimal PASCAL like syntax.
In terms of implementing something, that would make the job easier.

As such, Ruby designers might have more  carefully considered how'd
they expect programmers
to understand Ruby libraries for that's how Ruby development of Ruby
programs would proceed.
In asking this question via IRC, a programmer responded that Ruby
libraries are complex thereby
requiring all those modules etc. and that this creates additional
difficulties in documenting what
the libraries do. In fact that's no kind of answer. It's a plattitude.
Almost all engineering problems
are complex and difficult. Managing complexity is everybody's problem.

I will stop here. I don't want to say more or less. I don't want to
start discussing dynamic v.
static typed languages either. All I have done is identify a single
area of Ruby which requires
some continuous improvement. In working with Ruby and Rails for about
one week in some
detail, this is the only serious qualm I have.