tag docstring per 'resa' parola chiave

Question

Ci sono alcuni tag per docstring in Python, come @param e @return, ad esempio:

def my_method(a_param): 
    ''' @param a_param: Description of this param 
     @return: The return value of the method 
    ''' 
    return int(a_param) * (other or 1) 

cosa posso usare per documentare i generatori? specialmente il yield parola chiave, come:

def my_generator(from=0): 
    ''' @param from: The initial value 
     @yield: A lot of values 
    ''' 
    yield a_value 

Capisco che @return an iterator può essere utilizzato qui, ma non so se è corretta, perché un generatore può restituire anche i valori.

Grazie.

Answer 1

riterrei @return essere appropriato in questo caso poiché la funzione restituisce effettivamente un oggetto iteratore con un metodo next o send. La validità della dichiarazione x = my_generator(from=3) implica che my_generator restituisce effettivamente qualcosa. Lo fa semplicemente senza usare la dichiarazione return per farlo.

In un certo senso, le funzioni contenenti una dichiarazione o un'espressione yield si comportano come classi, perché sono fabbriche che restituiscono oggetti con proprietà prevedibili. Tuttavia, poiché le funzioni del generatore possono essere dichiarate e invocate come metodi di istanza, non li considero come classi.