Wishlist proposal, documenting fn arg as in or out or mod

[Dom DiSc]

Just to put it in clearer words:

On Tuesday, 20 June 2023 at 15:01:17 UTC, Cecil Ward wrote:
> I would love to be able to document my arguments as in or out 
> but also as read-write

This is what "ref" is for.

> We already have "in". Good thing.
>
> However it has got mixed up with const so that you can’t 
> declare something as both.

Hurray!
I'm so glad this is not allowed. "in" means const. There is no 
gain in "const const".

> However I hate using ref for input-output arguments as it isn’t 
> visible at the call site

This is true for all annotations.

> and a ref could be just ref-for-implementation

Sorry, but if a function takes a "ref" that it never modifies, I 
would call this simply a bug. It prevents you from calling it 
with const or immutable arguments while this would be perfectly 
valid.
So "ref" is documenting that the function will modify this 
parameter. You can never expect anything else (or maybe curse the 
stupid developer that missed marking the parameter as const).