[DOCS] Improve documentation on syntax for function return types

[vladvrabie]

trafficstars

TLDR: Nowhere on the documentation website (that I could find) is it written that syntax -> forward SomeType or -> move SomeType is valid for return types.

Context: I've been learning to use Cpp2 from the documentation website. I've started porting one of my projects to Cpp2 to learn, to see what is possible and what is still missing.

I was trying to override the operator<< for one of my classes:

operator<< : (inout stream: std::ostream, piece: Piece) -> _ = { /* implementation details */ }

After discovering that -> _ doesn't return what I expected, returning -> std::ostream& gives a parsing error. After multiple tries, I finally discovered this revelatory error message only 'forward' and 'move' return passing style are allowed from functions (at 'out') and that this -> forward std::ostream is valid syntax.

Suggestion: please update the documentation website (probably at return values) to cover this syntax

In searching for this syntax, I searched the repo and found it in the regression-tests files.

Suggestion 2: Maybe add a paragraph in the docs that it is incomplete and WIP and that many more examples of Cpp2 syntax can be found in the regression-tests folder.

For documentation issues:

Suggestion 3: Add a documentation issue template so that it will be automatically labeled with 'documentation'