Fix parse bug with toplevel methods. Allow RDoc in =begin rdoc/=end comments (experimental)

git-svn-id: svn+ssh://ci.ruby-lang.org/ruby/trunk@6066 b2dd03c8-39d4-4d8f-98ff-823fe69b080e

4 files changed, 54 insertions, 26 deletions

diff --git a/lib/rdoc/README b/lib/rdoc/README
index 0c10d0ea69..6e234e31a5 100644
--- a/lib/rdoc/README
+++ b/lib/rdoc/README
@@ -240,7 +240,15 @@ can see the formatted result in EXAMPLE.rb and Anagram.
 
 = Markup
 
-Comment blocks can be written fairly naturally. 
+Comment blocks can be written fairly naturally, either using '#' on
+successive lines of the comment, or by including the comment in 
+an =begin/=end block. If you use the latter form, the =begin line
+must be flagged with an RDoc tag:
+
+  =begin rdoc
+  Documentation to 
+  be processed by RDoc.
+  =end
 
 Paragraphs are lines that share the left margin. Text indented past
 this margin are formatted verbatim.
diff --git a/lib/rdoc/code_objects.rb b/lib/rdoc/code_objects.rb
index c48f5957b2..9ba351961b 100644
--- a/lib/rdoc/code_objects.rb
+++ b/lib/rdoc/code_objects.rb
@@ -404,6 +404,15 @@ module RDoc
     @@all_classes = {}
     @@all_modules = {}
 
+    def comment=(t)
+      if @c
+        fail t
+      else
+        @c = true
+      end
+      super
+    end
+
     def TopLevel::reset
       @@all_classes = {}
       @@all_modules = {}
diff --git a/lib/rdoc/parsers/parse_rb.rb b/lib/rdoc/parsers/parse_rb.rb
index e5276bf6c9..9988b71337 100644
--- a/lib/rdoc/parsers/parse_rb.rb
+++ b/lib/rdoc/parsers/parse_rb.rb
@@ -624,7 +624,14 @@ class RubyLex
       ungetc
 
       @ltype = nil
-      Token(TkRD_COMMENT).set_text(str)
+
+      if str =~ /\A=begin\s+rdoc/i
+        str.sub!(/\A=begin.*\n/, '')
+        str.sub!(/^=end.*/m, '')
+        Token(TkCOMMENT).set_text(str)
+      else
+        Token(TkRD_COMMENT)#.set_text(str)
+      end
     end
 
     @OP.def_rule("\n") do
@@ -1394,7 +1401,7 @@ module RDoc
       @read = []
       catch(:eof) do
         begin
-          parse_statements(@top_level)
+          parse_toplevel_statements(@top_level)
         rescue Exception => e
           $stderr.puts "\n\n"
           $stderr.puts "RDoc failure in #@input_file_name at or around " +
@@ -1546,26 +1553,30 @@ module RDoc
       res
     end
 
-    def parse_statements(container, single=NORMAL, current_method = nil)
+    def parse_toplevel_statements(container)
+      comment = collect_first_comment
+      look_for_directives_in(container, comment)
+      container.comment = comment unless comment.empty?
+      parse_statements(container, NORMAL, nil, comment)
+    end
+    
+    def parse_statements(container, single=NORMAL, current_method=nil, comment='')
       nest = 1
       save_visibility = container.visibility
-
-      if container.kind_of?(TopLevel)
-        comment = collect_first_comment
-        look_for_directives_in(container, comment)
-        container.comment = comment unless comment.empty?
-      else
-        comment = ''
-      end
+      
+#      if container.kind_of?(TopLevel)
+#      else
+#        comment = ''
+#      end
 
       non_comment_seen = true
-
+      
       while tk = get_tk
-
+        
         keep_comment = false
-
+        
         non_comment_seen = true unless tk.kind_of?(TkCOMMENT)
-
+        
 #         $stderr.puts "===== #{tk.inspect}"
 #         blank_line_seen = true
 #         while tk.kind_of?(TkNL)
@@ -1713,7 +1724,7 @@ module RDoc
 
       end
     end
-
+    
     def parse_class(container, single, tk, comment, &block)
       progress("c")
 
@@ -1867,7 +1878,7 @@ module RDoc
       @stats.num_methods += 1
       line_no = tk.line_no
       column  = tk.char_no
-
+      
       start_collecting_tokens
       add_token(tk)
       add_token_listener(self)
@@ -1949,20 +1960,20 @@ module RDoc
           meth.visibility = :public
         end
       end
-
+      
       parse_statements(container, single, meth)
-
+      
       remove_token_listener(meth)
-
+      
       meth.comment = comment
     end
-
+    
     def skip_method(container)
       meth =  AnyMethod.new("", "anon")
       parse_method_parameters(meth)
       parse_statements(container, false, meth)
     end
-
+    
     # Capture the method's parameters. Along the way,
     # look for a comment containing 
     #
diff --git a/lib/rdoc/ri/ri_options.rb b/lib/rdoc/ri/ri_options.rb
index b9ee21f073..4c8531aa47 100644
--- a/lib/rdoc/ri/ri_options.rb
+++ b/lib/rdoc/ri/ri_options.rb
@@ -5,7 +5,7 @@ module RI
 
   require 'rdoc/ri/ri_display'
 
-  VERSION_STRING = "beta1"
+  VERSION_STRING = "ri: beta1"
   CVS_ID         = "$Id$";
 
   class Options
@@ -171,7 +171,7 @@ module RI
     # Show the version and exit
     def show_version
       cvs_info = CVS_ID.split
-      puts "ri #{VERSION_STRING} (#{cvs_info[2]} #{cvs_info[3]})"
+      puts "#{VERSION_STRING} (#{cvs_info[2]} #{cvs_info[3]})"
       exit(0)
     end
 
@@ -230,7 +230,7 @@ module RI
 
     # Return the doc_dir as an array, or nil if no overriding doc dir was given
     def paths
-      @doc_dir ? [ @doc_dir ] : nil
+      defined?(@doc_dir) ? [ @doc_dir ] : nil
     end
 
     # Return an instance of the displayer (the thing that actually writes