Forum: Ruby Making rdoc see module-level documentation

Announcement (2017-05-07): www.ruby-forum.com is now read-only since I unfortunately do not have the time to support and maintain the forum any more. Please see rubyonrails.org/community and ruby-lang.org/en/community for other Rails- und Ruby-related community platforms.
753dcb78b3a3651127665da4bed3c782?d=identicon&s=25 Brian Candler (Guest)
on 2007-03-29 07:36
(Received via mailing list)
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')
}
This topic is locked and can not be replied to.