Python: how to document the return value when returning multiple values, using epytext?

Question

A simple function:

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

How would you document the (multiple) return value using epytext-style?

As a single tuple?

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

Or with separate @return tags for each variable? (is it even "legal"?)

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

I don't us epytext, but definitely the former. You are returning a tuple of two values, not returning two values. In python's typing, this would be written as `def foo() -> Tuple[int, int]` — FHTMitchell, Sep 17 '18 at 07:21

score 1 · Accepted Answer · answered Sep 17 '18 at 09:12

in Python, a tuple literal is created by the comma, not the parens (except for the empty tuple literal () which is a bit of a special case), so return a, b first creates a tuple then returns it. IOW, you are not "returning multiple values" but a single tuple object, so the answer is obvious.

Python: how to document the return value when returning multiple values, using epytext?

1 Answers1