Тег строки документа для ключевого слова 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, ведут себя как классы, поскольку они являются фабриками, которые возвращают объекты с предсказуемыми свойствами.Однако, поскольку функции генератора сами могут быть объявлены и вызваны как методы экземпляра, я не считаю их классами.