add ref-return-scope table

[WalterBright]

The table with all the permutations should help.

[dlang-bot]

Thanks for your pull request, @WalterBright!

Bugzilla references

Your PR doesn't reference any Bugzilla issue.

If your PR contains non-trivial changes, please reference a Bugzilla issue or create a manual changelog.

[maxhaton]

Is there a good reason why these permutations even exist?

[maxhaton]

A table is good but much better is to enforce a canonical order for each semantic expressible

[WalterBright]

Is there a good reason why these permutations even exist?

Legacy code compatibility.

A table is good but much better is to enforce a canonical order for each semantic expressible

Possibly true, but who wants to update all their code?

[pbackus]

iirc the eventual plan is to require that return be written directly before the attribute it modifies (either as return ref or return scope), but disallowing ref return is a breaking change, so for now we're stuck with this awkwardness.

I think the best way to explain this stuff is to start with just ref and scope, and then introduce return as a modifier that can apply to either ref or scope (but not both). Giving all of the possible combinations equal standing in a table (including combinations where the attributes do not interact at all, like scope ref) obscures the underlying semantic rules, and is more likely to make the reader's eyes glaze over than to teach them anything.

Happy to take a crack at writing some documentation for this myself if desired.

[WalterBright]

A table is good but much better is to enforce a [...]

the eventual plan is to require [...]

This PR is documenting the way D behaves now. Initiatives to improve the language should be a separate discussion. The table expresses the meaning better than the prose did.

[dkorpel]

return is not an interpretation

Suggested change

	$(TROW `return`, `return`)
	$(TROW `return`, $(RETURN_SCOPE))

[WalterBright]

It depends on the context. See mtype.buildScopeRef

[dukc]

iirc the eventual plan is to require that return be written directly before the attribute it modifies (either as return ref or return scope), but disallowing ref return is a breaking change, so for now we're stuck with this awkwardness.

Well once we have language editions this can be done. It's otherwise a great plan IMO, but has one problem. How would return be applied to the this reference of a struct or union? void memFun() return ref {/+...+/} does not parse.