From: Brian Candler <B.Candler@...>
Date: 2007-03-29T14:34:33+09:00
Subject: Making rdoc see module-level documentation

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')
}