Please do not use 'auto' return types without thoroughly describing the interface

[Piotr Klos]

On Monday, 25 December 2017 at 03:23:33 UTC, Neia Neutuladh wrote:
> If you have a function with a return type listed as `auto`, 
> please thoroughly describe what interface the return value 
> provides.
>

I would just like to say that I strongly agree. Lack of 
documentation of template parameters and other unspecified types 
in interfaces, like auto return types is one of the primary 
reasons for people to turn away from template libraries and 
regard templates as obscure.

> "Returns a forward range of Elem", where Elem is a template 
> parameter, is fine, for instance.
>
> But look at std.regex.RegexMatch.front:
>
> "Functionality for processing subsequent matches of global 
> regexes via range interface"
>
> It has an example that mentions a `hit` property. Other parts 
> of the RegexMatch interface mention `pre` and `post` 
> properties. What are they? It is a mystery!
>
> Turns out that the return type is a Captures struct, and that 
> could be made explicit with little effort. (Such as 
> https://github.com/dlang/phobos/pull/5963.)
>
> This *is* redundant. Looking at the source code lets you find 
> the return type in less than thirty seconds. Or you can put 
> into your code: `pragma(msg, ReturnType!(func).stringof);` 
> However, I imagine we'd lose a lot of people in the "see 
> missing documentation" → "look at source code" step.

This is not redundant. The documentation doesn't give enough 
information to use the interface, so its simply incomplete.