'yield'关键字的Docstring标签 [英] Docstring tag for 'yield' keyword

问题描述

python中有一些docstrings的标签，例如 @param 和 @return ，例如： p>

There are some tags for docstrings in python, like @param and @return, for example:

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 关键字，如：

What can I use for documenting generators? specially the yield keyword, like:

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

我明白 @return一个迭代器可以在这里使用，但我不知道如果它是正确的，因为发电机也可以返回值。

I understand that @return an iterator can be used here, but I don't know if it's correct because a generator can return values also.

谢谢。

推荐答案

在这种情况下，我会认为 @return 是合适的，因为函数实际上返回一个具有的迭代器对象或发送方法。语句 x = my_generator（from = 3）的有效性意味着 my_generator 真的会返回一些东西。它只是这样做，而不使用 return 语句来做到这一点。

I would consider @return to be appropriate in this case because the function actually returns an iterator object with a next or send method. The validity of the statement x = my_generator(from=3) implies that my_generator really does return something. It merely does so without using the return statement to do it.

在某些方面，包含code> yield 语句或表达式类似于类，因为它们是返回具有可预测属性的对象的工厂。然而，因为生成器函数本身可以被声明和调用为实例方法，我不认为它们是类。

In some ways, functions containing a yield statement or expression behave like classes, because they are factories that return objects with predictable properties. However, because generator functions can themselves be declared and invoked as instance methods, I do not think of them as classes.

这篇关于'yield'关键字的Docstring标签的文章就介绍到这了，希望我们推荐的答案对大家有所帮助，也希望大家多多支持IT屋！