From: Stefano Crocco <stefano.crocco@...>
Date: 2010-10-20T16:37:17+09:00
Subject: rdoc doesn't recognize block comments anymore

Hello to everyone.

I just found out a strange issue with rdoc and I'm not sure whether there's 
something wrong in my system (gentoo linux) or with rdoc itself. The problem 
is that rdoc doesn't consider documentation in block comments (=begin/=end 
comments) anymore. For example, take a file with the following contents:

=begin rdoc
 Doc for X
=end
module X
  
=begin rdoc
   Doc for Y
=end
  class Y
    
=begin rdoc
 Doc for Z
=end
    def z
    end
  end
end

If I run it through rdoc (using the rdoc gem version 2.5.11 and ruby 1.9.2), 
it tells me that I have 1 undocumented module, 1 undocumented class and 1 
undocumented method. Accordingly, the generated html files don't contain any 
description for X, Y and z. If I replace the block comments with ordinary 
comments, then everything works correctly.

I am sure that block comments used to work with rdoc at least until about 
January this year. After that, I started using YARD as documentation system 
and didn't try rdoc anymore until yesterday.

Can anybody reproduce this behaviour? Is this a known issue (I couldn't find 
anything neither using google nor on the RDoc project page), or a deliberate 
change in rdoc (I couldn't find mention of it in the rdoc History.txt file, 
however)? Should I report it as a bug?

Thanks in advance

Stefano