Best way to document “splatted” parameter with YAR

Question

Closed. This question is opinion-based. It is not currently accepting answers.

---

Want to improve this question? Update the question so it can be answered with facts and citations by editing this post.

Closed 2 years ago.

I have a method that should take 1+ parameters of any class, similar to Array#push:

def my_push(*objects)
  raise ArgumentError, 'Needs 1+ arguments' if objects.empty?
  objects.each do |obj| 
    puts "An object was pushed: #{obj.inspect}"
    @my_array.push obj
  end
end

What is the best way to document the method parameters using YARD syntax?

Edit:

I realize that my original question was a bit too vague and didn't quite specify what I was looking for.

A better question would be, what is the best way to specify the arity of a method (1-∞ in this case) in YARD when using a splatted parameter? I know I could just specify it in the text, but it seems like there should be a tag or something similar to specify arity.

Answer 1

YARD's creator, lsegal, states that the appropriate thing to do is provide an @overload for expected invocations. However, this doesn't really provide much clarity in the case of an Array#push-like method.

I suggest that you use the @param tag and use Array<Object> as the argument type or provide an @overload that looks nice.

Here's a comparison of the two:

class Test
  # A test method
  #
  # @param [Array<Object>] *args Any number of Objects to push into this collection
  # @return nil
  def push(*args); end

  # Another test method
  #
  # @overload push2(obj, ...)
  #   @param [Object] obj An Object to push
  #   @param [Object] ... More Objects
  def push2(*args); end
end