Reduce document difference between RDoc::Parser::Ruby and RDoc::Parser::PrismRuby

[tompng]

Fix these bugs/incompatibilities which was making makes many differences between two parsers

module DidYouMean
  # NameErrorCheckers = Object.new is now evaluated outside of this singleton class.
  class << (NameErrorCheckers = Object.new)
    # DidYouMean::NameErrorCheckers::NameErrorCheckers is not documented anymore
  end
end

# Nodoc comment on the end of parameter line is now working
def self.new2(user, password, host, port, path,
              typecode = nil, arg_check = true) # :nodoc:
end

module Enumerable
  # Fix syntax tree traverse order. Fix bug that this comment is ignored.
  def to_set(klass = Set, *args, &block)
  end unless condition
end

# Documents both ruby and c definition of new and initialize. (accepts duplicated entry only for method "new")
# files: Fiddle/Function.html, Fiddle/Handle.html, Fiddle/Pinned.html and more

# This include is not listed in the documentation anymore
cxx = Module.new do
  include MakeMakefile
end

# Superclass: `Object` → `"DelegateClass(File)"`
class Tempfile < DelegateClass(File)
end

module Psych
  # Superclass: `::Hash` → `Hash`
  class Omap < ::Hash
  end
end

String.include(
  Module.new {
    # This is not a toplevel method anymore
    def byteindex(needle, offset = 0)
    end
  }
)

class Dir
  module Tmpname
    # Check for :nodoc: and skip creating module RANDOM
    class << RANDOM # :nodoc:
    end
  end
end

DefaultResolver = self.new
# Don't create module DefaultResolver if it is already defined as a constant
def DefaultResolver.replace_resolvers new_resolvers
  @resolvers = new_resolvers
end

Diff

Diff of generating html files in ruby/ruby between RDoc::Parser::Ruby and RDoc::Parser::PrismRuby

Some link of constant names in document text are removed/added

CGI/Util.html
Exception.html
Gem/DefaultUserInteraction.html
Gem/Security.html
MakeMakefile.html
NEWS/NEWS-3_2_0_md.html
Net/HTTPHeader.html
OpenSSL/Buffering.html
OpenSSL/PKey/DSA.html
OpenSSL/PKey/EC.html
OpenSSL/PKey/RSA.html
Ripper/Filter.html
UnicodeNormalize.html

Trailing garbage text removed from meta tag

Fiddle/DLError.html
Prism/ConstantPathNode.html
Prism/ParenthesesNode.html

Call-seq improved or changed(space added/removed)

Delegator.html
Fiddle/Error.html
FileUtils.html
Gem/Commands/QueryCommand.html
MonitorMixin/ConditionVariable.html
Net/HTTPHeader.html
YAMLTree.html
SyntaxSuggest/CleanDocument.html
YAML/DBM.html

Wrong include/extend removed

CGI.html
ERB/Util.html
Gem/BasicSpecification.html
Gem/Commands/SetupCommand.html
Gem/Platform.html
Gem/Util.html
MakeMakefile.html
OpenURI/Meta.html

Missing constant added

DidYouMean.html
Gem/Validator.html

Missing document comment added

DidYouMean.html

Missing method added

Digest/SHA2.html
ERB/Util.html

Method source improved

Gem/Commands/SetupCommand.html

Method visibility improved

Gem/Commands/SetupCommand.html
IPSocket.html
Ractor.html

Wrong method removed

Resolv/SZ.html
SyntaxSuggest.html

Wrong metaprogramming comment treated as method comment

Gem/Specification.html
Object.html

##
# metaprogramming method comment
require 'path_treated_as_metaprogramming_method_name'

Wrong comment removed

Net/HTTP.html
Net.html

RDoc bug was suppressed by another bug, but not supperssed anymore

Net/HTTPFatalError.html

Method added

Pathname.html
Comment # -> path # :nodoc: is not considered to be a :nodoc: comment in PrismRuby.

index.html

Link to Gem::Request and UnicodeNormalize is added (unknown)
Ripper::Lexer is removed (it has #:nodoc: internal use only comment comment)
EXCEPTION_TYPE added (RDoc::Parser::Ruby does not handle EXCEPTION_TYPE = HTTPError #)

[st0012]

Thank you 👍
2 questions wrt the Prism-based parser:

• Do you think we should automate the diff comparison on CI?
• Are we close to turning on Prism Ruby parser by default? Since rdoc is now a bundled gem and the prism gem is pretty stable, I think adding it as a dependency may be easier now.

[st0012]

I used merge commit for this PR because the changes are cleanly separated (❤️) and I think these context will be valuable for future development.

[tompng]

Do you think we should automate the diff comparison on CI?

About diff between master and pull-request:
Looks great. It will help us for now and on. Small change sometimes makes large difference in output html.

About comparing RDoc::Parser::PrismRuby and RDoc::Parser::Ruby:
After switching or removing old parser, maybe we won't need the comparison. For now, I think it will help us because #1149 also brings difference too.

Are we close to turning on Prism Ruby parser by default?

I think it's almost ready for switching.
We need to compare in bundled gems and some other gems (rails) and check if diffs are acceptable.