We need better documentation for functions with ranges and templates

[Chris Wright via Digitalmars-d]

On Mon, 14 Dec 2015 19:38:26 +0000, Jack Stouffer wrote:
> If you're trying to use Phobos without knowing what template constraints
> and ranges are, you're going to have a bad time.

I completely agree about ranges.

On that note, it would be nice if std.range actually told you what 
interface a range has to honor. It points you to Andrei's article, but 
that uses C++.

It would also be awesome if std.algorithm reminded you of that interface 
right there in the package documentation, seeing as it makes such 
extensive use of ranges. It does better than std.range by linking to 
Ali's book, but Ali introduces things to you rather slowly.

Yes, std.range.primitives defines isInputRange and friends. However, it's 
not defining ranges in general, just a collection of specific types of 
ranges. It's not telling you that foreach works with ranges. And it's 
using odd terminology -- the module is called "primitives" when it really 
defines the interface that a range must adhere to (and provides a random 
smattering of convenience methods that don't seem to belong), and it 
calls the methods and properties that a range must define "primitives" 
for maximum confusion.

So for ranges.

Template constraints, on the other hand? Not so much. You can ignore them 
and hope that your stuff works and get confused when it doesn't. Or you 
can glance at a method's signature and see that it's two or three lines 
long and get scared. And when you decide, a few weeks or months into 
using D, to use templates, you'll quickly discover it's far less work not 
to use constraints and you get much better error messages.

> I'm not sure what else to say here. You can't expect to use the language
> to it's fullest without understanding these features.

Right, but std.algorithm is full of stuff that novices need to use early 
on. They're not trying to use the language to its fullest; they're just 
trying to use the basic parts of the standard library.

There's also the problem that the template constraint is made so 
prominent when the examples are far more useful for most people.