On Monday, 25 December 2017 at 22:48:39 UTC, H. S. Teoh wrote:
On Mon, Dec 25, 2017 at 04:26:52PM +0000, Piotr Klos via
Digitalmars-d wrote:
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.
While I agree that all template parameters ought to be
documented and all auto return types thoroughly described, I
disagree with explicit naming of auto return types. The whole
point of auto return types is to return an *opaque* type that
user code should not depend on, apart from what the
documentation says you can do with the type. It's a matter of
encapsulation, i.e., "you can do X, Y, Z with the return value
of this function, everything else is none of your business".
Or, in other words, if your code can't possibly work without
(...)
While I agree with the sentiment that encapsulation is good and
all, I think the emphasis is on the wrong thing here. It seems
that you are happy to take forever thinking about the right thing
to do, even at the price of eternal unusability. The desing goals
of standard library should be the exact opposite, i.e. make
things 100% usable even at the cost of making less features, and
then maybe later make more features if a need appears.
If something is not usable yet, it shouldn't be in the stdlib!
So in my humble opinion the process for getting something into a
stdlib should be create + document + assess usability -> repeat
-> publish or reject, not create -> publish -> document,
especially for template libs!
Otherwise you risk that the lib won't be very usable after all
despite the best intentions (if users are even patient enouh to
wait for the proper docs). For example look at all the template
parameters in boost c++ libraries, most of which are never used.
