pythondocstringepytext

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


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

Solution

  • 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.