From 54f6e5bd5dd4e1d0687880d369ad54891be5b1ab Mon Sep 17 00:00:00 2001
From: Nathan Beyer <nbeyer@gmail.com>
Date: Thu, 22 Mar 2018 21:50:52 -0500
Subject: [PATCH] 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
---
 lib/rdoc/tom_doc.rb       | 12 ++++++--
 test/test_rdoc_tom_doc.rb | 60 ++++++++++++++++++++++++++++++++++++++-
 2 files changed, 68 insertions(+), 4 deletions(-)

diff --git a/lib/rdoc/tom_doc.rb b/lib/rdoc/tom_doc.rb
index 2b594b7d84..625a6b5cfa 100644
--- a/lib/rdoc/tom_doc.rb
+++ b/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
-
diff --git a/test/test_rdoc_tom_doc.rb b/test/test_rdoc_tom_doc.rb
index 6a6822d50d..27a3e6f178 100644
--- a/test/test_rdoc_tom_doc.rb
+++ b/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
-