Menu
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.
365
Yield is a keyword in Python that is used to return from a function without destroying the states of its local variable and when the function is called, the execution starts from the last yield statement.
In Python, we use double underscore before the attributes name to make them inaccessible/private or to hide them.
yield in Python can be used like the return statement in a function. When done so, the function instead of returning the output, it returns a generator that can be iterated upon. You can then iterate through the generator to extract items. Iterating is done using a for loop or simply using the next() function.
In simpler words, the yield keyword will convert an expression that is specified along with it to a generator object and return it to the caller. Hence, if you want to get the values stored inside the generator object, you need to iterate over it.
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.
139
If you love us? You can donate to us via Paypal or buy me a coffee so we can maintain and grow! Thank you!
Donate Us With
