Блог

В 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 это можно использовать здесь, но я не знаю, правильно ли это, потому что генератор также может возвращать значения.

Спасибо.

Я бы счел @return это уместным в этом случае, потому что функция фактически возвращает объект итератора с next send помощью метода or. Действительность утверждения x = my_generator(from=3) подразумевает, что my_generator это действительно что-то возвращает. Он просто делает это, не используя return для этого инструкцию.

В некотором смысле функции, содержащие yield оператор или выражение, ведут себя как классы, потому что они являются фабриками, которые возвращают объекты с предсказуемыми свойствами. Однако, поскольку функции генератора сами по себе могут быть объявлены и вызваны как методы экземпляра, я не думаю о них как о классах.