Python: как документировать возвращаемое значение при возврате нескольких значений, используя эпитекст?

Question

Простая функция:

def foo():
    a = 1
    b = 2
    return a, b

Как бы вы задокументировали (многократное) возвращаемое значение, используя стиль epytext?

Как один кортеж?

def foo():
    """
    This function
    @return (a, b): a tuple of a and b representing...
    """
    a = 1
    b = 2
    return a, b

Или с отдельными @return тегами для каждой переменной?(это даже "законно"?)

def foo():
    """
    This function
    @return a: a int representing...
    @return b: a int representing...
    """
    a = 1
    b = 2
    return a, b

Answer 1

в Python, литерал кортежа создается запятой, а не паренами (за исключением пустого литерала кортежа (), который является частным случаем), поэтому return a, b сначала создает tuple, а затем возвращаетЭто.Итак, вы не «возвращаете несколько значений», а один tuple объект, поэтому ответ очевиден.