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.
