Add support for 'Raises' lines in TomDoc parser

* For the special case of 'initialize', handle 'Raises' as the
  indicator of the Returns section.
* Stop treating Raises lines as multine text and let them be
  their own paragraphs

Author: nbeyer

lib/rdoc/tom_doc.rb

@@ -180,12 +180,19 @@ def build_paragraph margin
 
       case type
       when :TEXT then
-        @section = 'Returns' if data =~ /\AReturns/
+        @section = 'Returns' if data =~ /\A(Returns|Raises)/
 
         paragraph << data
       when :NEWLINE then
         if :TEXT == peek_token[0] then
-          paragraph << ' '
+          # Lines beginning with 'Raises' in the Returns section should not be
+          # treated as multiline text
+          if 'Returns' == @section and
+            peek_token[1].start_with?('Raises') then
+            break
+          else
+            paragraph << ' '
+          end
         else
           break
         end
@@ -255,4 +262,3 @@ def tokenize text
   end
 
 end
-

test/test_rdoc_tom_doc.rb

@@ -301,6 +301,44 @@ def test_parse_returns
     assert_equal expected, @TD.parse(text)
   end
 
+  def test_parse_returns_with_raises
+    text = <<-TEXT
+Do some stuff
+
+Returns a thing
+Raises ArgumentError when stuff
+Raises StandardError when stuff
+    TEXT
+    expected =
+      doc(
+        para('Do some stuff'),
+        blank_line,
+        head(3, 'Returns'),
+        blank_line,
+        para('Returns a thing'),
+        para('Raises ArgumentError when stuff'),
+        para('Raises StandardError when stuff'))
+
+    assert_equal expected, @TD.parse(text)
+  end
+
+  def test_parse_raises_without_returns
+    text = <<-TEXT
+Do some stuff
+
+Raises ArgumentError when stuff
+    TEXT
+    expected =
+      doc(
+        para('Do some stuff'),
+        blank_line,
+        head(3, 'Returns'),
+        blank_line,
+        para('Raises ArgumentError when stuff'))
+
+    assert_equal expected, @TD.parse(text)
+  end
+
   def test_parse_returns_multiline
     text = <<-TEXT
 Do some stuff
@@ -320,6 +358,27 @@ def test_parse_returns_multiline
     assert_equal expected, @TD.parse(text)
   end
 
+  def test_parse_returns_multiline_and_raises
+    text = <<-TEXT
+Do some stuff
+
+Returns a thing
+  that is multiline
+Raises ArgumentError
+    TEXT
+
+    expected =
+      doc(
+        para('Do some stuff'),
+        blank_line,
+        head(3, 'Returns'),
+        blank_line,
+        para('Returns a thing', ' ', 'that is multiline'),
+        para('Raises ArgumentError'))
+
+    assert_equal expected, @TD.parse(text)
+  end
+
   def test_parse_signature
     text = <<-TEXT
 Do some stuff
@@ -518,4 +577,3 @@ def test_tokenize_returns_multiline
   end
 
 end
-