Il modo migliore per documentare il parametro "splattato" con YARD?

Question

Ho un metodo che dovrebbe prendere 1+ parametri di qualsiasi classe, simile a 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 

Qual è il modo migliore per documentare i parametri del metodo utilizzando la sintassi YARD?

Edit:

mi rendo conto che la mia domanda iniziale era un po 'troppo vaga e non riusciva a specificare quello che stavo cercando.

Una domanda migliore sarebbe, qual è il modo migliore per specificare l'arità di un metodo (1-∞ in questo caso) in YARD quando si utilizza un parametro splattato? So che potrei semplicemente specificarlo nel testo, ma sembra che ci sia dovrebbe essere un tag o qualcosa di simile a specificare l'arità.

Answer 1

Il creatore di YARD, lsegal, afferma che the appropriate thing to do is provide an @overload for expected invocations. Tuttavia, questo non fornisce molta chiarezza nel caso di un metodo Array#push -like.

Suggerisco di utilizzare il tag @param e di utilizzare Array<Object> come tipo di argomento o di fornire un @overload bello.

Ecco un confronto tra i due:

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