Remove dead Section#extract_comment method

Earlopain split section-comment extraction out of Section#extract_comment in
#1639 and added the TODO "Remove when the ripper parser has been
removed". With ripper gone, the Ruby parser's own extract_section_comment is
the only path that fires; every production caller hands Section.add_comment a
comment that has already been stripped of the ":section:" header.

- Drop Section#extract_comment, and simplify Section#add_comment to just
  validate and append.
- Update test_add_comment / test_description to pass the empty,
  pre-extracted comments the parser actually produces today.
- Drop test_extract_comment.

Also restore the explanatory note above Mixin#module that the prior commit
removed too aggressively. The method's resolution dance is still live for
the C parser (which passes unresolved local names); only the Ruby parser's
mixins arrive pre-resolved.

Author: claude

lib/rdoc/code_object/context/section.rb

@@ -63,10 +63,10 @@ def ==(other)
   # Adds +comment+ to this section
 
   def add_comment(comment)
-    comments = Array(comment)
-    comments.each do |c|
-      extracted_comment = extract_comment(c)
-      @comments << extracted_comment unless extracted_comment.empty?
+    Array(comment).each do |c|
+      next if c.nil?
+      raise TypeError, "unknown comment #{c.inspect}" unless RDoc::Comment === c
+      @comments << c unless c.empty?
     end
   end
 
@@ -98,37 +98,6 @@ def legacy_aref
     CGI.escape(title).gsub('%', '-').sub(/^-/, '')
   end
 
-  ##
-  # Extracts 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 extract_comment(comment)
-    case comment
-    when nil
-      RDoc::Comment.new ''
-    when RDoc::Comment then
-      if comment.text =~ /^#[ \t]*:section:.*\n/ then
-        start = $`
-        rest = $'
-
-        comment.text = if start.empty? then
-                         rest
-                       else
-                         rest.sub(/#{start.chomp}\Z/, '')
-                       end
-      end
-
-      comment
-    else
-      raise TypeError, "unknown comment #{comment.inspect}"
-    end
-  end
-
   def inspect # :nodoc:
     "#<%s:0x%x %p>" % [self.class, object_id, title]
   end

lib/rdoc/code_object/mixin.rb

@@ -71,6 +71,9 @@ def inspect # :nodoc:
   # lookup behavior.
   #
   # As of the beginning of October, 2011, no gem includes nonexistent modules.
+  #
+  # The Ruby parser passes an already-resolved full-path +name+, so most of this
+  # logic only runs for the C parser, which passes the unresolved local name.
 
   def module
     return @module if @module

test/rdoc/rdoc_context_section_test.rb

@@ -19,9 +19,9 @@ def test_add_comment
 
     klass = file1.add_class RDoc::NormalClass, 'Klass'
 
-    c1 = RDoc::Comment.new "# :section: section\n", file1
-    c2 = RDoc::Comment.new "# hello\n",             file1
-    c3 = RDoc::Comment.new "# world\n",             file1
+    c1 = RDoc::Comment.new "",       file1
+    c2 = RDoc::Comment.new "# hello\n", file1
+    c3 = RDoc::Comment.new "# world\n", file1
 
     s = @S.new klass, 'section', c1
 
@@ -45,9 +45,9 @@ def test_description
     klass = file1.add_class RDoc::NormalClass, 'Klass'
 
 
-    c1 = comment "# :section: section\n", file1, :ruby
-    c2 = comment "# hello\n",             file1, :ruby
-    c3 = comment "# <tt>world</tt>\n",    file1, :ruby
+    c1 = comment '',                   file1, :ruby
+    c2 = comment "# hello\n",          file1, :ruby
+    c3 = comment "# <tt>world</tt>\n", file1, :ruby
 
     s = @S.new klass, 'section', c1, @store
     assert_equal '', s.description
@@ -83,14 +83,6 @@ def test_equals
     refute_equal @s, other
   end
 
-  def test_extract_comment
-    assert_equal '',    @s.extract_comment(comment('')).text
-    assert_equal '',    @s.extract_comment(comment("# :section: b\n")).text
-    assert_equal '# c', @s.extract_comment(comment("# :section: b\n# c")).text
-    assert_equal '# c',
-                 @s.extract_comment(comment("# a\n# :section: b\n# c")).text
-  end
-
   def test_hash
     other = @S.new @klass, 'other', comment('# comment', @top_level)