How do I add a name for the returned values?

[Saransh-cpp]

I want to add a Name column to the "Returned" values (just like it is present in "Parameters"). Could someone please help me in turning the Name column "on"?

Thank you!

[pawamoy]

It's not possible right now. This has been partially discussed in #300.

I have trouble seeing how this could be achieved:

Returns:
    a (b): x.

This one is not ambiguous: a would be used as the name, while b would be used as the type. But:

Returns:
    a: x.

Currently, a is used as the type. How to understand that the user wants to use it as a name instead?

[pawamoy]

By the way, what docstring style do you use 🙂 ?

[Saransh-cpp]

Oh, I see.

Right now for the return statements, I am using a mixture of both styles (the first one wherever the name is important and the second one where users can ignore the name) because of the current implementation of return values in mkdocstrings. But I think it would be better to have it of the form -

Returns:
    a (b): x.

If the users want both implementations to be included then I don't know if it is possible but can we check if the docstring contains () before :? That could indicate that the name and the type, both are provided.

Lastly, thanks for this awesome documentation library! :)

[pawamoy]

Maybe we could change the syntax then. If you want to override the return annotation, you have to put the type in parentheses. I think that's what you suggest?

Syntax	Interpretation
name: x.	Use name as name.
(type): x.	No name. Use type as return annotation.
name (type): x.	Use name as name, and type as return annotation.

[Saransh-cpp]

Yes, this looks perfect! Thanks!

[pawamoy]

Named items in Returns section are now supported.

[Saransh-cpp]

Awesome! Thanks!