yield'关键字的文档字符串标签

Question

在Python中，有一些用于文档字符串的标签，比如 @param 和 @return，例如：

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)

我可以用什么来记录生成器呢？特别是 yield 这个关键词，比如：

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

我知道这里可以用 @return an iterator，但是我不确定这样是否正确，因为生成器也可以返回值。

谢谢。

Answer 1

在这种情况下，我认为使用 @return 是合适的，因为这个函数实际上返回了一个迭代器对象，这个对象有 next 或 send 方法。语句 x = my_generator(from=3) 的有效性意味着 my_generator 确实返回了一些东西。只是它并不是通过 return 语句来返回的。

在某种程度上，包含 yield 语句或表达式的函数表现得有点像类，因为它们是工厂，返回具有可预测属性的对象。不过，由于生成器函数本身可以被声明并作为实例方法调用，所以我并不把它们看作类。