Ignore leading and trailing lines in :section: blocks

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

3 files changed, 41 insertions, 5 deletions

diff --git a/lib/rdoc/README b/lib/rdoc/README
index 583f7f3b0c..60650dd88b 100644
--- a/lib/rdoc/README
+++ b/lib/rdoc/README
@@ -427,7 +427,17 @@ this margin are formatted verbatim.
 	<tt>:section:</tt> is used as the section heading, and the
 	remainder of the comment containing the section is used as
 	introductory text. Subsequent methods, aliases, attributes,
-	and classes will be documented in this section.
+	and classes will be documented in this section. A :section:
+	comment block may have one or more lines before the :section:
+	directive. These will be removed, and any identical lines at
+	the end of the block are also removed. This allows you to add
+	visual cues such as
+
+           # ----------------------------------------
+	   # :section: My Section
+	   # This is the section that I wrote.
+	   # See it glisten in the noon-day sun.
+           # ----------------------------------------
 
     [<tt>call-seq:</tt>]
         lines up to the next blank line in the comment are treated as
diff --git a/lib/rdoc/code_objects.rb b/lib/rdoc/code_objects.rb
index 134ac398e9..d6c4f1bdb9 100644
--- a/lib/rdoc/code_objects.rb
+++ b/lib/rdoc/code_objects.rb
@@ -126,10 +126,36 @@ module RDoc
         @title = title
         @@sequence.succ!
         @sequence = @@sequence.dup
-        if comment
-          @comment = comment.sub(/.*$/, '')
-          @comment = nil if @comment.empty?
+        set_comment(comment)
+      end
+
+      private
+
+      # Set the comment for this section from the original comment block
+      # If the first line contains :section:, strip it and use the rest. Otherwise
+      # remove lines up to the line containing :section:, and look for 
+      # those lines again at the end and remove them. This lets us write
+      #
+      #   # ---------------------
+      #   # :SECTION: The title
+      #   # The body
+      #   # ---------------------
+
+      def set_comment(comment)
+        return unless comment
+
+        if comment =~ /^.*?:section:.*$/
+          start = $`
+          rest = $'
+          if start.empty?
+            @comment = rest
+          else
+            @comment = rest.sub(/#{start.chomp}\Z/, '')
+          end
+        else
+          @comment = comment
         end
+        @comment = nil if @comment.empty?
       end
     end
 
diff --git a/lib/rdoc/parsers/parse_rb.rb b/lib/rdoc/parsers/parse_rb.rb
index 2f76b95d31..15b3484cb7 100644
--- a/lib/rdoc/parsers/parse_rb.rb
+++ b/lib/rdoc/parsers/parse_rb.rb
@@ -2312,7 +2312,7 @@ module RDoc
         when "section"
           context.set_current_section(param, comment)
           comment.clear
-          break
+          break 
         else
           warn "Unrecognized directive '#{directive}'"
           break