From: Markus Fischer <markus@...>
Date: 2011-05-28T17:39:15+09:00
Subject: Problem getting rdoc documenting all top level module/classes in a file

Hi,

I'm struggling to understand how rdoc expects my source to be organized
so it documents everything in it I want.

Using ruby 1.9.2p180 and rdoc 3.6.1 and the following source layouts
I've missing documentations:

------------------8<-----------------------------
$ cat test2.rb
require 'something'
=begin rdoc
findmeindoc
=end
module Foo
    class Bar
    end
end
$ rm -Rf doc && rdoc -v test2.rb
Parsing sources...
100% [ 1/ 1]  test2.rb
  class Bar (undocumented)


Generating Darkfish format into ...
------------------8<-----------------------------

In this case, as soon as I put any kind of code above the rdoc of my
module, the module itself does not get processed anymore. However I
really prefer having includes and maybe necessary initializations at the
top. Because when I move it *below* the rdoc but *before* the module
definition, it works:

------------------8<-----------------------------
$ cat test3.rb
=begin rdoc
findmeindoc
=end
require 'something'
module Foo
    class Bar
    end
end
$ rm -Rf doc && rdoc -v test3.rb
Parsing sources...
100% [ 1/ 1]  test3.rb
  class Foo::Bar (undocumented)
  module Foo (undocumented)


Generating Darkfish format into ...
------------------8<-----------------------------

Similar when I've two modules in a file, only the first one gets processed:

------------------8<-----------------------------
$ cat test8.rb
=begin rdoc
findmeindoc
=end
module Foo
end

=begin rdoc
findme2indoc
=end
module Frob
end
$ rm -Rf doc && rdoc -v test8.rb
Parsing sources...
100% [ 1/ 1]  test8.rb
  module Foo


Generating Darkfish format into ...
------------------8<-----------------------------

Can this be worked around? Basically I'd like it to document everything
have, except things I flag with nodoc.

thanks,
- Markus