etiqueta de cadena de documentación para la palabra clave 'rendimiento'

Question

Hay algunas etiquetas para las cadenas de documentación en Python, como @param y @return, por ejemplo:

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) 

¿Qué puedo usar para documentar los generadores? especialmente la yield palabra clave, como:

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

entiendo que @return an iterator puede usar aquí, pero no sé si es correcto, ya que un generador puede devolver valores también.

Gracias.

Answer 1

Considero que @return es apropiado en este caso porque la función realmente devuelve un objeto iterador con un método next o send. La validez de la declaración x = my_generator(from=3) implica que my_generator realmente devuelve algo. Simplemente lo hace sin usar la instrucción return para hacerlo.

De alguna manera, las funciones que contienen una declaración 0 expresión yield se comportan como clases, porque son fábricas que devuelven objetos con propiedades predecibles. Sin embargo, como las funciones del generador pueden declararse e invocarse como métodos de instancia, no las considero como clases.