Parameter 'type': Expected type Parlour::Types::Proc, got type Parlour::Types::Raw

[SnowSzn]

Describe the bug Sord crashes when parsing YARD documentation that uses @param &block [Proc] Block.

While this style is not idiomatic (the & is not normally included in YARD tags), some extensions I have used automatically generate documentation with it.

I have already fixed this in my codebase by simply replacing all &block with block, but thought it could be a good idea to leave this issue here.

The crash only happens with & (&block), but not with other symbols such as * (*args)

YARD does not to crash, though it complains in the output (check output below).

To Reproduce Simple piece of code that reflects the error in my codebase when running sord:

# frozen_string_literal: true

module Test
  #
  # Initalize
  #
  # @param *args [Array<String>] Arguments
  #
  # @return [void]
  #
  def self.init(*args)
    @data = args
  end

  #
  # Iterator
  #
  # @param &block [Proc] Block
  # @yieldparam [String]
  #
  # @return [void]
  #
  def self.each(&block)
    @data.compact.each(&block) if block_given?
  end
end

Test.init("arg1", nil, "arg2", "arg3", nil, "arg4")
Test.each { |i| p i }

Expected behavior Sord should not crash when encountering @param &block .... Ideally, it should either:

• Treat it as if it were @param block ..., or
• Emit a warning that the syntax is not supported/idiomatic.

Actual behavior Sord crashes when processing the above code if @param &block ... is present. No crash occurs with @param *args ....

Calling sord test.rbs --trace in the gem root folder produces:

[INFER] Assuming from filename you wish to generate in RBS format
[INFO ] Running YARD...
[warn]: @param tag has unknown parameter name: *args
    in file `lib/test.rb' near line 11
[warn]: @param tag has unknown parameter name: &block
    in file `lib/test.rb' near line 25
Files:           2
Modules:         1 (    1 undocumented)
Classes:         0 (    0 undocumented)
Constants:       1 (    1 undocumented)
Attributes:      0 (    0 undocumented)
Methods:         2 (    0 undocumented)
 50.00% documented
[ERROR] An internal error occurred while running Sord: Parameter 'type': Expected type Parlour::Types::Proc, got type Parlour::Types::Raw with hash 129340816
Caller: C:/Ruby33-x64/lib/ruby/gems/3.3.0/gems/sord-7.1.0/lib/sord/generator.rb:483
Definition: C:/Ruby33-x64/lib/ruby/gems/3.3.0/gems/parlour-9.1.2/lib/parlour/rbs_generator/block.rb:14 (Parlour::RbsGenerator::Block#initialize)
C:/Ruby33-x64/lib/ruby/gems/3.3.0/gems/sorbet-runtime-0.5.12414/lib/types/configuration.rb:296:in `call_validation_error_handler_default': Parameter 'type': Expected type Parlour::Types::Proc, got type Parlour::Types::Raw with hash 129340816 (TypeError)
Caller: C:/Ruby33-x64/lib/ruby/gems/3.3.0/gems/sord-7.1.0/lib/sord/generator.rb:483
Definition: C:/Ruby33-x64/lib/ruby/gems/3.3.0/gems/parlour-9.1.2/lib/parlour/rbs_generator/block.rb:14 (Parlour::RbsGenerator::Block#initialize)

    raise TypeError.new(opts[:pretty_message])
          ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
        from C:/Ruby33-x64/lib/ruby/gems/3.3.0/gems/sorbet-runtime-0.5.12414/lib/types/configuration.rb:303:in `call_validation_error_handler'
        from C:/Ruby33-x64/lib/ruby/gems/3.3.0/gems/sorbet-runtime-0.5.12414/lib/types/private/methods/call_validation.rb:322:in `report_error'
        from C:/Ruby33-x64/lib/ruby/gems/3.3.0/gems/sorbet-runtime-0.5.12414/lib/types/private/methods/call_validation.rb:230:in `block in validate_call'
        from C:/Ruby33-x64/lib/ruby/gems/3.3.0/gems/sorbet-runtime-0.5.12414/lib/types/private/methods/signature.rb:213:in `each_args_value_type'
        from C:/Ruby33-x64/lib/ruby/gems/3.3.0/gems/sorbet-runtime-0.5.12414/lib/types/private/methods/call_validation.rb:227:in `validate_call'
        from C:/Ruby33-x64/lib/ruby/gems/3.3.0/gems/sorbet-runtime-0.5.12414/lib/types/private/methods/_methods.rb:277:in `block in _on_method_added'
        from C:/Ruby33-x64/lib/ruby/gems/3.3.0/gems/sord-7.1.0/lib/sord/generator.rb:483:in `new'
        from C:/Ruby33-x64/lib/ruby/gems/3.3.0/gems/sord-7.1.0/lib/sord/generator.rb:483:in `block in add_methods'
        from C:/Ruby33-x64/lib/ruby/gems/3.3.0/gems/sord-7.1.0/lib/sord/generator.rb:307:in `each'
        from C:/Ruby33-x64/lib/ruby/gems/3.3.0/gems/sord-7.1.0/lib/sord/generator.rb:307:in `add_methods'
        from C:/Ruby33-x64/lib/ruby/gems/3.3.0/gems/sord-7.1.0/lib/sord/generator.rb:622:in `add_namespace'
        from C:/Ruby33-x64/lib/ruby/gems/3.3.0/gems/sord-7.1.0/lib/sord/generator.rb:639:in `block in populate'
        from C:/Ruby33-x64/lib/ruby/gems/3.3.0/gems/sord-7.1.0/lib/sord/generator.rb:639:in `each'
        from C:/Ruby33-x64/lib/ruby/gems/3.3.0/gems/sord-7.1.0/lib/sord/generator.rb:639:in `populate'
        from C:/Ruby33-x64/lib/ruby/gems/3.3.0/gems/sord-7.1.0/lib/sord/generator.rb:659:in `run'
        from C:/Ruby33-x64/lib/ruby/gems/3.3.0/gems/sord-7.1.0/lib/sord/parlour_plugin.rb:77:in `generate'
        from C:/Ruby33-x64/lib/ruby/gems/3.3.0/gems/sord-7.1.0/exe/sord:92:in `block (2 levels) in <top (required)>'
        from C:/Ruby33-x64/lib/ruby/gems/3.3.0/gems/commander-5.0.0/lib/commander/command.rb:187:in `call'
        from C:/Ruby33-x64/lib/ruby/gems/3.3.0/gems/commander-5.0.0/lib/commander/command.rb:157:in `run'
        from C:/Ruby33-x64/lib/ruby/gems/3.3.0/gems/commander-5.0.0/lib/commander/runner.rb:444:in `run_active_command'
        from C:/Ruby33-x64/lib/ruby/gems/3.3.0/gems/commander-5.0.0/lib/commander/runner.rb:58:in `run!'
        from C:/Ruby33-x64/lib/ruby/gems/3.3.0/gems/commander-5.0.0/lib/commander/delegates.rb:18:in `run!'
        from C:/Ruby33-x64/lib/ruby/gems/3.3.0/gems/commander-5.0.0/lib/commander/import.rb:7:in `block in <top (required)>'

Additional information

• Based on my tests this issue seems isolated to &block in @param names.
• Although @param &block is not idiomatic YARD usage, it can appear when documentation is auto-generated by extensions.
• Making Sord handle this gracefully would improve robustness and prevent crashes.

[AaronC81]

Thanks for the report! I can reproduce this with your test case.

From a code search it looks like this pattern is used in a reasonable number of projects, so I agree that Sord should support this.

There's also a rare subset of these which just write...

@param & [Proc]

...without a name, so a solution which can handle this as well would be good.