@!method warns about unknown params when used above method with different signature

[jtrees]

When using the @!method directive above a method declaration, the parser seems to get confused about which method signature to use and uses the one belonging to the method beneath the docs, instead of the one described in the directive.

Example

class Foo
  # @!scope class
  # @!method greet(name)
  #   @param [String] name
  #   @return [String]
  def greet
    "hello #{name}"
  end
end

Steps to reproduce

This is the minimal reproduction for the issue. I've done my best to remove all extraneous code and unique environment state on my machine before providing these steps:

1. Save the code from above as foo.rb.
2. Run the following command: yard doc --fail-on-warning --no-output --no-cache foo.rb

Actual Output

[warn]: @param tag has unknown parameter name: name 
    in file `/path/to/foo.rb' near line 6

Expected Output

There should be no warnings.

Additional Notes

You might be wondering why one would even do such a strange thing as referenced here. Actually, I'm just trying to document what the interactor gem produces. It takes the call method defined on any interactor object and performs its voodoo.

Environment details:

• OS: elementary OS 5.0 (based on Ubuntu 18.04)
• Ruby version (ruby -v): ruby 2.6.2p47 (2019-03-13 revision 67232) [x86_64-linux]
• YARD version (yard -v): yard 0.9.20

I have read the Contributing Guide.

[castwide]

Have you considered using the @overload tag instead?

class Foo
  # @!scope class
  # @overload greet(name)
  #   @param [String] name
  #   @return [String]
  def greet
    "hello #{name}"
  end
end

[jtrees]

Huh. Well, it's not exactly intuitive (I wouldn't consider a class method to be an overload of an instance method) but it does yield the result I'm going for. Thanks!

[castwide]

Another option is to put the @!method directive above the class:

# @!method self.greet(name)
#   @param [String] name
#   @return [String]
class Foo
  def greet
    "hello #{name}"
  end
end

Deciding which is more appropriate depends on your goal. This version adds both Foo#greet and Foo.greet(name) to the documentation.

[lsegal]

You should use @overload if the method is defined in Ruby source. Directives are meant to synthesize methods that do not exist in Ruby code only.

# @overload greet(name)
#   @param name [String] the name
# @overload greet(foo)
#   Another optional overload of greet
def greet; end