20

The Python docs say that "the markup used for the Python documentation is reStructuredText". My question is: How is a block comment supposed to be written to show multiple return values?

def func_returning_one_value():
    """Return just one value.

    :returns: some value
    :rtype: str
    """

def func_returning_three_values():
    """Return three values.

    How do I note in reStructuredText that three values are returned?
    """

I've found a tutorial on Python documentation using reStructuredText, but it doesn't have an example for documenting multiple return values. The Sphinx docs on domains talks about returns and rtype but doesn't talk about multiple return values.

Marty Chang
  • 6,269
  • 5
  • 16
  • 25
  • Seems like anything goes with docstrings, as long as it is clear and concise and consistent throughout a project. Write something that suits your purpose. [PEP 257](https://www.python.org/dev/peps/pep-0257/) has some broad conventions. Look through the Python dot py files on your computer and see how the devs did it. – wwii Sep 29 '16 at 04:06
  • 1
    Like [os.walk()](https://github.com/python/cpython/blob/a237032d7732bd9142e3802b77767d342bb30870/Lib/os.py#L277) which returns multiple things. – wwii Sep 29 '16 at 04:15

2 Answers2

16

There is a compromised solution: just write in normal Markdown texts. e.g.

def func(a, b):
    """

    :param int a: first input
    :param int a: second input
    :returns: 
        - x - first output
        - y - second output
    """

    return x, y

This will generate the following document:

enter image description here

Almost what we want, right?

The shortcoming for this is that you cannot specify return type for every element. You would have to write it by yourself, such as 

"""
:returns:
    -x (:py:class:`int`) - first output
"""
ComeOnGetMe
  • 1,029
  • 9
  • 11
8

As wwi mentioned in the comments, the detailed format to be used is not strictly defined.

For myself, I usually use the Field List notation style you use above. It supports line breaks, so just break where you feel is necessary

def my_func(param1, param2):
    """
    This is a sample function docstring

    :param param1: this is a first param
    :param param2: this is a second param
    :returns: tuple (result1, result2) 
        WHERE
        str result1 is .... 
        str result2 is ....        
    """
monkut
  • 42,176
  • 24
  • 124
  • 155
  • Doesn't work with me. Do you have to install something special, or tell Sphinx that it has to use field list? – PatriceG Nov 28 '17 at 10:47