Properly documenting the return type in the "Returns" section when using google docstring style

[tazend]

Hi,

I noticed that when using the google parser for docstrings, it is not possible to properly document the return type of the return value within the Returns section itself without using type annotations or giving the value an explicit name.

Example

Consider the following test function, and generate the documentation for it with the google parser:

def test_func():
    """Return an integer.

    Returns:
        int: The integer
    """
    print("Hello friends!")

This results in the following:

Additionally, the following warning is generated:

No type or annotation for returned value 'int'

I would however expect the following to be generated:

The workaround to generate the correct layout like in the above screenshot is of course using type annotations, and rewriting it like this:

def test_func() -> int:
    """Return an integer.

    Returns:
        The integer
    """
    print("Hello friends!")

However, I think it would still be useful having the ability to simply specify the return type in the "Returns" section and getting the same layout as when using type annotations (and not giving the return value a name).

The primary reason I'm asking is because I'm working on a Cython project, and the github source-code viewer is absolutely not a friend of mixing Cython code with type annotations, and displays this mess. Well, thats more of a github problem, but I'd still appreciate if it would be possible to have the correct layout generated without the use of type annotations :)

[pawamoy]

Hello! We support this:

def test_func():
    """Return an integer.

    Returns:
        (int): The integer
    """
    print("Hello friends!")

This is consistent with how parameters are documented, and was the only viable solution to support named items in returns sections, without a configuration option. The plan is to add such a configuration, because I agree this is non-standard and therefore unexpected 🙂 (I'd love that the Google style got revised though!)

[tazend]

Hi,

thanks, that works good for now with the paranthesis 😄

[sanzoghenzo]

Not sure if I should add this here or open another issue, but there's another aspect that isn't correctly parsed following the google style: the return types of class properties.

As per sphinx-napoleon example:

class ExampleClass:
    @property
    def readonly_property(self):
        """str: Properties should be documented in their getter method."""
        return 'readonly_property'

Unfortunately the project I'm helping with the documentation (pyRevit) cannot yet move to type annotations because it must support IronPython 2.7, so this feature would really help us better document the code!

[pawamoy]

@sanzoghenzo how should this get rendered? Do you expect a Returns table/list with just the type, and an empty description?

[sanzoghenzo]

Thanks for taking the time to review this!

I don't have a strong opinion for this; maybe just add it after the property literal, at the same line of the property name?
Or simply as a Type: <type> before the description?

I'm not much into style (as long as it's not ugly!), what matters to me is that the info is accessible and readable 😉

[pawamoy]

OK, then I'll reuse what is available, i.e. a dynamically added Returns section at the end of the docstring 🙂 Not the prettiest but you'll have the info rendered!