diff --git a/ChangeLog b/ChangeLog
index cc9a1b2ab9..886e654ebd 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,15 @@
+Sat Dec  4 14:28:56 2004  Dave Thomas  <dave@pragprog.com>
+
+	* lib/rdoc/code_objects.rb (RDoc::Context::Section::set_comment):
+	  Section comments may now be bracketed by lines which are
+	  ignored. You can now write
+	      # -----------
+	      # :section: Dave's Section
+	      # comment material
+	      # -----------
+	   The lines before :section: are removed, and identical lines at the end are 
+	   also removed if present.
+
 Fri Dec  3 12:25:21 2004  Nobuyoshi Nakada  <nobu@ruby-lang.org>
 
 	* st.h: fix prototype for C++.
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