Making rdoc see module-level documentation

Ruby
1

I’m having trouble getting rdoc to display the top-level documentation
for a
module.

A test case is attached below:

  • lib/zzz/zzz.rb contains my main overview documentation about the ‘Zzz’
    module. I want this to be displayed when the user clicks on Zzz.

  • lib/zzz/bar.rb and lib/zzz/foo.bar contain other classes in module
    Zzz.

  • I generate the HTML using any of these three commands:

    rake doc
    rdoc lib
    rdoc lib/zzz/zzz.rb lib/zzz/bar.rb lib/zzz/foo.rb

However, clicking on Zzz doesn’t show the module level documentation
(although the constants defined in lib/zzz/zzz.rb are shown). In fact,
the
module level documentation isn’t included anywhere.

$ find doc -type f | xargs grep -i interesting
$

If I put comments at the top of lib/zzz/bar.rb they are displayed. But
that’s not really a logical place to put them, and will break if I later
add
lib/zzz/aardvark.rb

So, is there a way to tell rdoc to take its module documentation from a
particular file?

Thanks,

Brian.

==> ./lib/zzz/zzz.rb <==
=begin
This is the background info on the Zzz module

Lots of interesting stuff goes here
=end

module Zzz

MAX_SLEEP_WINKS = 40
class ZzzError < RuntimeError; end
end

==> ./lib/zzz/bar.rb <==
module Zzz
class Bar
end
end

==> ./lib/zzz/foo.rb <==
module Zzz
class Foo
end
end

==> ./Rakefile <==
require ‘rake/rdoctask’

task :default do
puts “Type ‘rake --tasks’ for a list of options”
end

Rake::RDocTask.new(“doc”) { |rdoc|
rdoc.rdoc_dir = ‘doc’
rdoc.title = “Application Documentation”
rdoc.options << ‘–line-numbers’ << ‘–inline-source’
rdoc.rdoc_files.include(‘lib/**/*.rb’)
}