Skip to content

Conversation

@tompng
Copy link
Member

@tompng tompng commented Jan 24, 2026

Fixes #398, #782, #816, #1555, #885, #1373, #1553

Although generated HTML has huge difference, many many bugs are fixed with RDoc::Parser::PrismRuby parser.
Diffs are mostly: many bugfixes, crossrefs, trailing whitespaces in syntax highlight, and perhaps few new bugs.
Old parser can be used with RDOC_USE_RIPPER_PARSER=1

@tompng tompng temporarily deployed to fork-preview-protection January 24, 2026 20:43 — with GitHub Actions Inactive
@matzbot
Copy link
Collaborator

matzbot commented Jan 24, 2026

🚀 Preview deployment available at: https://a0f2332e.rdoc-6cd.pages.dev (commit: d1eaa56)

# Here is the <tt>:call-seq:</tt> directive given for this method:
#
# :call-seq:
# \:call-seq:
Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

RDoc::Parser::Ruby specially handles :call-seq:.

# This is a call-seq
#   :call-seq: foo(x)
#
# This is a code block in RDoc::Parser::Ruby,
# but a second call-seq in RDoc::Prism::PrismRuby
#   :call-seq: foo(y)
#
# Code block in both parser
#   \:call-seq: foo(z)

def foo(*); end

Indented directives are allowed because indented :include: have special meaning.

# include a file with all lines indented
#   :include: file.rb

@tompng tompng force-pushed the prism_parser_as_default branch from 2445ddc to 74047b0 Compare January 31, 2026 04:54
@tompng tompng temporarily deployed to fork-preview-protection January 31, 2026 04:54 — with GitHub Actions Inactive
@tompng tompng force-pushed the prism_parser_as_default branch from 74047b0 to d1eaa56 Compare February 3, 2026 19:27
@tompng tompng deployed to fork-preview-protection February 3, 2026 19:27 — with GitHub Actions Active
@tompng
Copy link
Member Author

tompng commented Feb 4, 2026

Generating document in ruby/ruby, there's many difference between RDoc::Parser::PrismRuby and RDoc::Parser::RipperRuby.
Most differences are in <ul> tag of page navigation because some files are renamed/removed.
Here's a summary of all other document differences.

1 file renamed, 3 non-empty files deleted, 69 empty files deleted

1 file renamed

Renamed file: ZJIT.htmlRubyVM/ZJIT.html

The bug below is fixed:

module RubyVM::ZJIT
end

class << RubyVM::ZJIT # This moves /RubyVM/ZJIT.html to /ZJIT.html
end
3 non-empty files deleted.

All these three class/modules are surrounded by :stopdoc: .. :startdoc:, so it must not documented.

Resolv/DNS/Config/NXDomain.html
Resolv/DNS/Config/OtherResolvError.html
Resolv/DNS/Requester/RequestError.html
7 linked empty files deleted

All class/modules has :nodoc: comment or surrounded by :stopdoc: .. :startdoc:.

Prism/Translation/Ripper/Lexer.html
Ripper/Lexer.html
Resolv/DNS/Config.html
Resolv/DNS/Requester.html
Resolv/DNS/Resource.html
Resolv/DNS/Resource/IN.html
Resolv/DNS/SvcParam.html
62 unlinked empty files deleted
MakeMakefile/Logging.html
MakeMakefile/RbConfig.html
Net/HTTPBadResponse.html
Net/HTTPClientException.html
Net/HTTPError.html
Net/HTTPFatalError.html
Net/HTTPHeaderSyntaxError.html
Net/HTTPRetriableError.html
Net/ProtoAuthError.html
Net/ProtoCommandError.html
Net/ProtoFatalError.html
Net/ProtoRetriableError.html
Net/ProtoServerError.html
Net/ProtoSyntaxError.html
Net/ProtoUnknownError.html
Net/ProtocRetryError.html
Net/ProtocolError.html
Prism/Translation/Ripper/Lexer/Elem.html
Prism/Translation/Ripper/Lexer/State.html
Psych/Config.html
Resolv/DNS/DecodeError.html
Resolv/DNS/EncodeError.html
Resolv/DNS/Name.html
Resolv/DNS/Query.html
Resolv/DNS/Resource/ANY.html
Resolv/DNS/Resource/CAA.html
Resolv/DNS/Resource/CNAME.html
Resolv/DNS/Resource/DomainName.html
Resolv/DNS/Resource/Generic.html
Resolv/DNS/Resource/HINFO.html
Resolv/DNS/Resource/IN/A.html
Resolv/DNS/Resource/IN/AAAA.html
Resolv/DNS/Resource/IN/HTTPS.html
Resolv/DNS/Resource/IN/SRV.html
Resolv/DNS/Resource/IN/SVCB.html
Resolv/DNS/Resource/IN/ServiceBinding.html
Resolv/DNS/Resource/IN/WKS.html
Resolv/DNS/Resource/LOC.html
Resolv/DNS/Resource/MINFO.html
Resolv/DNS/Resource/MX.html
Resolv/DNS/Resource/NS.html
Resolv/DNS/Resource/PTR.html
Resolv/DNS/Resource/SOA.html
Resolv/DNS/Resource/TXT.html
Resolv/DNS/SvcParam/ALPN.html
Resolv/DNS/SvcParam/DoHPath.html
Resolv/DNS/SvcParam/Generic.html
Resolv/DNS/SvcParam/IPv4Hint.html
Resolv/DNS/SvcParam/IPv6Hint.html
Resolv/DNS/SvcParam/Mandatory.html
Resolv/DNS/SvcParam/NoDefaultALPN.html
Resolv/DNS/SvcParam/Port.html
Resolv/DNS/SvcParams.html
Ripper/Lexer/Elem.html
Ripper/Lexer/State.html
Socket/HostnameResolutionResult.html
Socket/HostnameResolutionStore.html
Timeout/Request.html
Timeout/State.html
Timeout/Sync.html
Win32/Registry/Constants.html
Win32/Registry/Error/Kernel32.html
Wrong crossref fixed in 5 files
file crossref change
Exception.html SyntaxSuggest#detailed_message Removed. SyntaxSuggest doesn't have that method. It is defined in anonymous module.
Ripper/Filter.html Ripper::Lexer.new Removed. It was linked to BasicObject.html#method-c-new
Gem/Resolver/APISet.html Set Link changed: ::SetGem::Resolver::Set
__/ruby/doc/NEWS/NEWS-4_0_0_md.html RubyVM::ZJIT.enable ZJIT file renamed (ZJIT.htmlRubyVM/ZJIT.html)
__/ruby/doc/jit/zjit_md.html RubyVM::ZJIT.stats ZJIT file renamed (ZJIT.htmlRubyVM/ZJIT.html)
CrossRef added in 50 files

Some might be problematic and needs backslash to suppress crossref.
Example:
Gem/Specification.html: "Source" in "OSI (Open Source Initiative)" is linked to Gem/Source.html

file added crossref
Gem/AvailableSet.html Resolver, RequestSet
Gem/BasicSpecification.html Specification, StubSpecification, Gem, Platform, Version
Gem/Command.html Gem
Gem/CommandManager.html Command
Gem/Commands/InstallCommand.html Gem
Gem/Commands/UninstallCommand.html Gem
Gem/ConfigFile.html Gem
Gem/ConsoleUI.html StreamUI
Gem/Dependency.html Gem
Gem/DependencyInstaller.html SpecFetcher
Gem/Ext/CmakeBuilder.html Gem
Gem/GemcutterUtilities.html Gem
Gem/Installer.html Version
Gem/Licenses.html Package
Gem/NameTuple.html Gem, Platform
Gem/PackageTask.html Gem, Package
Gem/Platform.html Gem
Gem/RequestSet.html Specification
Gem/Requirement.html Version
Gem/Resolver/APISet.html APISpecification, DependencyRequest
Gem/Resolver/APISpecification.html Specification
Gem/Resolver/ActivationRequest.html Specification
Gem/Resolver/BestSet.html IndexSet, APISet
Gem/Resolver/Conflict.html Specification
Gem/Resolver/DependencyRequest.html Dependency
Gem/Resolver/IndexSet.html IndexSpecification, DependencyRequest
Gem/Resolver/IndexSpecification.html Specification, IndexSet
Gem/Resolver/InstallerSet.html IndexSpecification, DependencyRequest
Gem/Resolver/LockSet.html IndexSpecification, DependencyRequest
Gem/Resolver/RequirementList.html Resolver::DependencyRequest, DependencyRequest
Gem/Resolver/Set.html Resolver, Specification, DependencyRequest
Gem/Resolver/SourceSet.html BestSet
Gem/Resolver/SpecSpecification.html Resolver::SpecSpecification, Resolver
Gem/Resolver/Specification.html Resolver::Specification
Gem/Resolver/VendorSet.html VendorSpecification, DependencyRequest
Gem/Resolver.html Dependency
Gem/S3URISigner.html Source
Gem/SafeMarshal.html Gem
Gem/SafeYAML.html Gem
Gem/Specification.html Gem, NameTuple, InvalidSpecificationException, Source
Gem/SpecificationPolicy.html InvalidSpecificationException, Specification#validate_for_resolution
Gem/Uninstaller.html Version, Gem
Gem/UnsatisfiableDependencyError.html Resolver, Requirement, Version
Gem/Version.html Requirement
Gem.html Gem
MakeMakefile RbConfig
Net/HTTPRequest.html HTTP
UnicodeNormalize.html UnicodeNormalize
__/ruby/doc/NEWS/NEWS-2_4_0.html Gem
__/ruby/doc/distribution/distribution_md.html Gem
Other crossref change in 2 files
file crossref change memo
OpenSSL/PKey/PKeyError.html OpenSSL::PKey::RSAError PKeyError.html../PKey.html#RSAError All other PKey::XXXError was linked to PKey.html#RSAError
Prism/Translation/Parser.html Prism::Translation::ParserCurrent Parser33.html../Translation.html#ParserCurrent Maybe improved
Other change in 29 files

Some files includes whitespace difference like this:

<pre class="ruby"><span class="ruby-identifier">code</span>
</pre>
<!-- ↓ -->
<pre class="ruby"><span class="ruby-identifier">code</span></pre>
  • Delegator.html

    • whitespace
    • Plain text ":method: freeze" removed from generated HTML
    • Method heading text __raise__()__raise__
  • DidYouMean/Correctable.html

    • Private constant SKIP_TO_S_FOR_SUPER_LOOKUP removed from document
  • DidYouMean.html

    • Missing constant NameErrorCheckers added
    • DidYouMean::Formatter shows correct document comment: "For compatibility:"
  • ERB/Util.html

    • include ERB::Escape correctly displayed in document
  • ErrorHighlight/CoreExt.html

    • Private constant SKIP_TO_S_FOR_SUPER_LOOKUP removed from document
  • FileUtils.html

    • Extended with module improved from StreamUtils_ to FileUtils::StreamUtils_
    • Arg of chdir improved from chdir (dir, verbose: nil) to chdir (dir, verbose: nil, &block)
  • Gem/Commands/SetupCommand.html

    • Wrong extend removed (extend called inside instance method is not module's extend)
      • FileUtils::Verbose
      • FileUtils
      • Gem::Commands::SetupCommand::MakeDirs
    • Private method removed
      • default_dir
      • prepend_destdir_if_present
      • install_file_list
      • install_file
      • remove_file_list
      • target_bin_path
      • bin_file_names
    • Wrong source of show_release_notes fixed
  • Gem/Specification.html

    • Ghost method unknown added
      • Invalid use of metaprogramming rdoc comment "##\n#" to an class variable assign is processed
    • CrossRef added
      • Source (in "OSI (Open Source Initiative)") may need backslash to suppress crossref
  • Gem/Validator.html

    • Constant ErrorData added
  • IPSocket.html

    • Public alias method getaddress_orig added
      • private; alias getaddress_orig getaddress doesn't creates a private alias in Ruby.
  • MakeMakefile.html

    • Wrong include MakeMakefile removed. (Module.new{include MakeMakefile})
    • CrossRef added
  • MonitorMixin/ConditionVariable.html

    • Callseq change
      • wait_until()wait_until() { || ... }
      • wait_while()wait_while () { || ... }
  • Net/HTTPHeader.html:

    • Callseq change
      • each_key()each_key(&block)
  • Net.html

    • Comment for constant HTTPSession = HTTP properly applied instaed of huge comment for Net::HTTP
  • Object.html

    • method rubygems/defaults/operating_system (defined in lib/rubygems.rb:1416) is added
      • ##\n# comment\nmetaprogramming_method "rubygems/defaults/operating_system" is a metaprogramming method comment
    • method unknown (defined in lib/rubygems.rb:1433) is added
      • ##\n# comment\nmetaprogrammign_method "embed#{expr}" is a metaprogramming method comment with method name unknown
  • OpenURI/Meta.html

    • Wrong extend OpenURI::Meta removed. (obj.extend Meta)
  • Prism/ParenthesesNode.html:

    • Metatag's content changed. Trailing --- removed.
      • before: <meta name="description" content="content ---">
      • after: <meta name="description" content="content">
  • Psych/Visitors/YAMLTree.html

    • Callseq improved from create(options = {}) to create(options = {}, emitter = nil)
  • Ractor.html

    • Private instance method recv removed
  • Singleton.html

    • Extend module name improved: SingletonClassPropertiesSingleton::SingletonClassProperties
  • SyntaxSuggest/CleanDocument.html

    • Callseq improved: { |line)| ... }{ |line| ... }
  • SyntaxSuggest.html

    • Method detailed_message removed (defined in anonymous module, not in module SyntaxSuggest)
  • Thread/ConditionVariable.html

    • Plain text "Document-method: ConditionVariable::new" removed from generated HTML
  • Thread/Queue.html

    • Plain text " Document-method: Queue::new" removed from generated HTML
  • Thread/SizedQueue.html

    • Plain text " Document-method: SizedQueue::new" removed from generated HTML
  • YAML/DBM.html:

    • index( keystr )index(keystr)

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

:stopdoc: can prevent indexing a class documented in another file

2 participants