Skip to content

Documentation silently dropped when certain constructs parsed #1553

Closed

Description

@zenspider

The released version of minitest v6 fail to generate the top level documentation for the Minitest namespace.

bad: minitest/minitest@d5c8842

(I'm about to commit a change to fix rdoc generation)

After a lot of bisecting, both with git and manually, I tracked it down to the following diff:

diff --git a/lib/minitest/sprint_plugin.rb b/lib/minitest/sprint_plugin.rb
index afd2f08..1d82218 100644
--- a/lib/minitest/sprint_plugin.rb
+++ b/lib/minitest/sprint_plugin.rb
@@ -2,7 +2,9 @@ require_relative "../minitest"
 
 # :stopdoc:
 class OptionParser # unofficial embedded gem "makeoptparseworkwell"
-  def hidden(...)         = define(...).tap { |sw| def sw.summarize(*) = nil }
+  def hidden(...)
+    define(...).tap { |sw| def sw.summarize(*) = nil }
+  end
   def deprecate(from, to) = hidden(from) { abort "#{from} is deprecated. Use #{to}." }
   def topdict(name)       = name.length > 1 ? top.long : top.short
   def alias(from, to)     = (dict = topdict(from) and dict[to] = dict[from])

It isn't endless methods because the rest of them work...
nor does it seem to be using a block on an endless, because the rest of the work...
nor does it seem to be the ... arg/call...

After much mangling, it appears to be the singleton method on sw but ONLY if that's done as an endless on an endless?

this works:

  def hidden(...) = define(...).tap { |sw| sw.define_singleton_method(:summarize) { |*_| nil } }

this works:

  def hidden(...)
    define(...).tap { |sw| def sw.summarize(*) = nil }
  end

this does not:

  def hidden(...) = define(...).tap { |sw| def sw.summarize(*) = nil }

my testing script:

rm -rf doc
rdoc -q --fmt ri lib
ri -Td doc -f rdoc --no-system --no-home --no-gems Minitest | rg '^= \w+ methods:'

(rg is just a fancier / faster grep... grep will work w/ tweaks)

Generating ri info and then running:

ri -Td doc -f rdoc --no-system --no-home --no-gems Minitest

should show output that lists class and instance methods and mentions "The top-level namespace for Minitest".


I think the worst part of this is that it is entirely silent about it. -D outputs literally nothing extra. And -V outputs way too much and shows

 91% [22/24]  lib/minitest/sprint_plugin.rb
  class OptionParser (undocumented)
    #alias (undocumented)
    ::plugin_sprint_options
    ::plugin_sprint_init (undocumented)
  module OptionParser::Minitest
    #topdict (undocumented)
    #deprecate
    #hidden

which is totally wrong, but you wouldn't guess that just looking at the run.

Activity

  1. tompng commented on Jan 9, 2026

    @tompng
    Member

    Endless method related bugs will be fixed with the new parser RDoc::Parser::PrismRuby (enabled with env RDOC_USE_PRISM_PARSER=1 for now) and we're planning to changing the default soon.

    The default RDoc::Parser::Ruby parser doesn't support endless method at all. Reaching endless method, any random result may happen.

    For example, this code:

    class A
      def foo.f = 42
      def bar; end
      def A.baz; end
    end
    class B; end

    Will be parsed as:

    class A
      def foo.f; = 42
        # RDoc assumes self == foo
        def baz1; end # Treated as foo.baz1
        def A.baz2; end # Documented as A.baz2
      end
      class B; end # Documented as A::B
    # end is missing.

    Related to #885 and #1373

  2. zenspider commented on Jan 9, 2026

    @zenspider
    MemberAuthor

    given that the whole class had been wrapped in a stopdoc/startdoc, I would have hoped that it simply skipped over the whole thing.

    "end is missing" would also be a nice clue that something went haywire... but nothing of the sort is emitted even using -DV.

  3. tompng commented on Feb 17, 2026

    @tompng
    Member

    Endless method definition is now supported with #1581
    Random parse failure will be also fixed by using Prism instead of hand written ruby parser implemented in RDoc.

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

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions