From: gsm.beamon / gmail.com [mailto:gsm.beamon / gmail.com] 
> > If RDoc ran the code it parsed, then it would open a security hole a
> > mile wide, as I could then run arbitrary code on the machines of
> > anyone producing documentation. That's why I chose not to do this.
> Perhaps.
> 
> But why do that? One only need to parse for the purpose of extracting
> documentation.

  class Foo
    include Object.const_get( gets.chomp )
  end

That's an extreme case, but one in which it is impossible to know via
parsing what module will be brought into the class.

Some slightly less absurd cases:

  class Foo
    if rand > 0.1
      include SuperExplodingFun
    end
  end


  FASHIONABLE_MODULE_OF_THE_WEEK = Enumerable
  class Foo
    include FASHIONABLE_MODULE_OF_THE_WEEK
  end


  class Object
    def self.get_all_the_standard_stuff
      include Enumerable
      include MySexyModule::HotStuff
    end
  end

  class Foo
    get_all_the_standard_stuff
  end

That last example is somewhat like what the Rails case that started all
this does - there's some code that indirectly pulls in the module. RDoc
can't know this without running the code, and the author of RDoc made
the choice not to run the code.

(And even if it did run the code, there are theoretically certain
non-deterministic cases like the first two I posted which it could never
handle in an automated way.)