Der beste Weg, um "gespritzte" Parameter mit YARD zu dokumentieren?

Question

Ich habe eine Methode, die 1+ Parameter jede Klasse, ähnlich wie Array#push nehmen soll:

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 

Was ist der beste Weg, um zu dokumentieren, die Verfahrensparameter mit YARD Syntax?

Edit:

Ich weiß, dass meine ursprüngliche Frage etwas zu vage war und nicht ganz fest, was ich suchte.

Eine bessere Frage wäre, was ist der beste Weg, um die Arität einer Methode (1-∞ in diesem Fall) in YARD anzugeben, wenn ein Splatter-Parameter verwendet wird? Ich weiß, dass ich es im Text nur spezifizieren konnte, aber es scheint, dass dort ein Tag sein sollte oder etwas Ähnliches, um Arity zu spezifizieren.

Answer 1

YARDs Schöpfer, Lsegal, besagt, dass the appropriate thing to do is provide an @overload for expected invocations. Dies führt jedoch im Fall eines Array#push-ähnlichen Verfahrens nicht wirklich zu einer deutlichen Klarheit.

Ich schlage vor, dass Sie das @param-Tag verwenden und Array<Object> als Argumenttyp verwenden oder ein @overload bereitstellen, das gut aussieht.

Hier ist ein Vergleich der beiden:

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