[ruby/rdoc] Add new ruby parser that uses Prism

(https://github.com/ruby/rdoc/pull/1144)

* Add a new ruby parser RDoc::Parser::PrismRuby

* Add a new ruby parser testcase independent from parser's internal implementation

* unknown meta method

* Use MethodSignatureVisitor only to scan params, block_params and calls_super

* Add calls_super test

* Drop ruby 2.6. Prism requires ruby >= 2.7

* Remove duplicated documentation comment from prism_ruby.rb

* Add test for wrong argument passed to metaprogramming method

* Rename visit_call_[DSL_METHOD_NAME] to make it distinguishable from visit_[NODE_TYPE]_node

* Method receiver switch of true/false/nil to a case statement

* Extract common part of add_method(by def keyword) and add meta_comment method

* Reuse consecutive comments array when collecting comments

* Simplify DSL call_node handling

* Refactor extracting method visibility arguments

https://github.com/ruby/rdoc/commit/fde99f1be6

lib/rdoc/markup/pre_process.rb

@@ -97,15 +97,18 @@ class RDoc::Markup::PreProcess
   # RDoc::CodeObject#metadata for details.
 
   def handle text, code_object = nil, &block
+    first_line = 1
     if RDoc::Comment === text then
       comment = text
       text = text.text
+      first_line = comment.line || 1
     end
 
     # regexp helper (square brackets for optional)
     # $1      $2  $3        $4      $5
     # [prefix][\]:directive:[spaces][param]newline
-    text = text.gsub(/^([ \t]*(?:#|\/?\*)?[ \t]*)(\\?):(\w+):([ \t]*)(.+)?(\r?\n|$)/) do
+    text = text.lines.map.with_index(first_line) do |line, num|
+      next line unless line =~ /\A([ \t]*(?:#|\/?\*)?[ \t]*)(\\?):([\w-]+):([ \t]*)(.+)?(\r?\n|$)/
       # skip something like ':toto::'
       next $& if $4.empty? and $5 and $5[0, 1] == ':'
 
@@ -120,8 +123,8 @@ class RDoc::Markup::PreProcess
         next "#{$1.strip}\n"
       end
 
-      handle_directive $1, $3, $5, code_object, text.encoding, &block
-    end
+      handle_directive $1, $3, $5, code_object, text.encoding, num, &block
+    end.join
 
     if comment then
       comment.text = text
@@ -148,7 +151,7 @@ class RDoc::Markup::PreProcess
   # When 1.8.7 support is ditched prefix can be defaulted to ''
 
   def handle_directive prefix, directive, param, code_object = nil,
-                       encoding = nil
+                       encoding = nil, line = nil
     blankline = "#{prefix.strip}\n"
     directive = directive.downcase
 
@@ -220,11 +223,11 @@ class RDoc::Markup::PreProcess
       # remove parameter &block
       code_object.params = code_object.params.sub(/,?\s*&\w+/, '') if code_object.params
 
-      code_object.block_params = param
+      code_object.block_params = param || ''
 
       blankline
     else
-      result = yield directive, param if block_given?
+      result = yield directive, param, line if block_given?
 
       case result
       when nil then

lib/rdoc/parser/ruby.rb

@@ -8,6 +8,12 @@
 #       by Keiju ISHITSUKA (Nippon Rational Inc.)
 #
 
+if ENV['RDOC_USE_PRISM_PARSER']
+  require 'rdoc/parser/prism_ruby'
+  RDoc::Parser.const_set(:Ruby, RDoc::Parser::PrismRuby)
+  return
+end
+
 require 'ripper'
 require_relative 'ripper_state_lex'
 

lib/rdoc/rdoc.gemspec

@@ -230,8 +230,9 @@ RDoc includes the +rdoc+ and +ri+ tools for generating and displaying documentat
   s.rdoc_options = ["--main", "README.rdoc"]
   s.extra_rdoc_files += s.files.grep(%r[\A[^\/]+\.(?:rdoc|md)\z])
 
-  s.required_ruby_version = Gem::Requirement.new(">= 2.6.0")
+  s.required_ruby_version = Gem::Requirement.new(">= 2.7.0")
   s.required_rubygems_version = Gem::Requirement.new(">= 2.2")
 
+  s.add_dependency 'prism', '>= 0.30.0'
   s.add_dependency 'psych', '>= 4.0.0'
 end

test/rdoc/test_rdoc_parser_ruby.rb

@@ -2,6 +2,8 @@
 
 require_relative 'helper'
 
+return if ENV['RDOC_USE_PRISM_PARSER']
+
 class TestRDocParserRuby < RDoc::TestCase
 
   def setup