Docstring tag for 'yield' keyword

Question

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)

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

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.

Thanks.

Answer 1

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.

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.