ProxyMethodError: Proxy cannot call method #to_sym on object 'Struct'

[mullermp]

I'm not able to render documentation for a class named Struct within a namespace.

Steps to reproduce

The minimal code to reproduce is this:

module Types
  # My struct documentation
  Struct = ::Struct.new(:a)
end

Then run yardoc on this.

Actual Output

The rendered documentation only has:

Inherits: Struct
Defined in: (unknown)

Generated output (different example) gives this stack trace:

[warn]: Load Order / Name Resolution Problem on Struct:
-
Something is trying to call to_sym on object Struct before it has been recognized.
This error usually means that you need to modify the order in which you parse files
so that Struct is parsed before methods or other objects attempt to access it.
-
YARD will recover from this error and continue to parse but you *may* have problems
with your generated documentation. You should probably fix this.
-

[error]: Unhandled exception in YARD::Handlers::Ruby::ConstantHandler:
  in `lib/white_label/types.rb`:151:

    151: Struct = ::Struct.new(

[error]: ProxyMethodError: Proxy cannot call method #to_sym on object 'Struct'
[error]: Stack trace:
    /Users/mamuller/.gem/ruby/3.0.2/gems/yard-0.9.27/lib/yard/code_objects/proxy.rb:194:in `rescue in method_missing'
    /Users/mamuller/.gem/ruby/3.0.2/gems/yard-0.9.27/lib/yard/code_objects/proxy.rb:191:in `method_missing'
    /Users/mamuller/.gem/ruby/3.0.2/gems/yard-0.9.27/lib/yard/code_objects/proxy.rb:54:in `initialize'
    /Users/mamuller/.gem/ruby/3.0.2/gems/yard-0.9.27/lib/yard/code_objects/class_object.rb:136:in `new'
    /Users/mamuller/.gem/ruby/3.0.2/gems/yard-0.9.27/lib/yard/code_objects/class_object.rb:136:in `superclass='
    /Users/mamuller/.gem/ruby/3.0.2/gems/yard-0.9.27/lib/yard/handlers/ruby/struct_handler_methods.rb:94:in `block in create_class'

Expected Output

Types::Struct would be documented as expected.

Environment details:

• OS: Mac OS
• Ruby version (ruby -v): ruby 3.0.2p107 (2021-07-07 revision 0db68f0233) [x86_64-darwin19]
• YARD version (yard -v): yard 0.9.27

I have read the Contributing Guide.

[lsegal]

This is definitely an issue with parsing that should be looked into.

In the meantime, a decent workaround to avoid this error would be to declare the Struct class that YARD is looking for up top:

# Ruby will just see this as re-opening the standard Struct class and ignore it
# @private
# @api private
class Struct; end

module Types
  # My struct documentation
  Struct = ::Struct.new(:a)
end

Not ideal but it's a fairly easy fix if this is blocking you.