Parametri di DEPURAZIONE del cantiere

Question

Ho ottenuto quello che presumevo fosse un utilizzo di macro yard piuttosto basico in cui ho una struttura hash con un numero di opzioni condivise tra più funzioni. Speravo di usare una macro semplicemente per evitare che dovessi replicare questa struttura dappertutto, ma non sembra funzionare così.

quello che mi aspettavo di lavoro è stato:

# @macro [new] my_hash 
# @param $1 [Hash,Array<Hash>] Inputted my_hash 
# @option $1 [String] :a Value for A. 
# @option $1 [String] :b Value for B. 
# @option $1 [String] :c Value for C. 

## 
# my_func does stuff 
# @macro my_hash h1 
def my_func h1 
end 

## 
# other_func does stuff 
# @macro my_hash h2 
def other_func h2, a, b 
end 

ed hanno H1 e H2 correttamente documentati. Penso di aver capito che almeno il $ 1 non funziona così prende invece dalla funzione stessa, ma posso chiamare entrambi i parametri h1 e sostituire $ 1 con h1 nella macro e non riesco ancora a ottenere quello che voglio .

L'esempio "Definizione di macro semplici" in http://rubydoc.info/docs/yard/file/docs/Tags.md#macro indica che posso farlo (notare che trovo esempi con @! Macro e alcuni senza, ma nessuno dei due sembra funzionare).

Non so molto sul cantiere, ma non funziona? C'è qualcosa di simile che posso fare per raggiungere il mio risultato? c'è una funzione di debug che spiegherebbe questo perché non si verificano errori nella console del server del cantiere?

Grazie

Answer 1

Come già specificato nella macro che dovrebbe essere ampliato per primo parametro del metodo, che non è necessario specificare quando l'espansione macro. Sembra inoltre impossibile stabilire quale parametro espandere la macro. Un'altra cosa è che puoi saltare in questo caso [new] e sembra che sia meglio usare @!macro invece di @macro.

# @!macro my_hash 
# @param $1 [Hash,Array<Hash>] Inputted my_hash 
# @option $1 [String] :a Value for A. 
# @option $1 [String] :b Value for B. 
# @option $1 [String] :c Value for C. 

## 
# my_func does stuff 
# @!macro my_hash 
def my_func h1 
end 

## 
# other_func does stuff 
# @!macro my_hash 
def other_func h2, a, b 
end 

Answer 2

io credo che si può realizzare quello che stai cercando per l'utilizzo di cantieri Reference Tags.

Dalla documentazione:

Se i dati di un tag inizia con (see OBJECT) si ritiene un "riferimento tag". Un tag di riferimento copia letteralmente i dati dei tag dal nome del tag specificato dall'OBJECT specificato. Per esempio, un metodo può copiare tutti tag @param da un determinato oggetto utilizzando la sintassi tag di riferimento:

# @param [String] user the username for the operation 
# @param [String] host the host that this user is associated with 
# @param [Time] time the time that this operation took place 
def clean(user, host, time = Time.now) end 

# @param (see #clean) 
def activate(user, host, time = Time.now) end 

Answer 3

Questo funziona con yardoc 0.9.8 (probabilmente qualsiasi versione):

# @!macro my_hash 
# @param $1 [Hash,Array<Hash>] Inputted my_hash 
# @option $1 [String] :a Value for A. 
# @option $1 [String] :b Value for B. 
# @option $1 [String] :c Value for C. 

## 
# my_func does stuff 
# @macro my_hash 
def my_func h1 
end 

## 
# other_func does stuff 
# @macro my_hash 
def other_func h2, a, b 
end 

Nota il punto esclamativo mancante! quando si chiama la macro con @macro. Questo è il yardoc syntax corretto.