We need better documentation for functions with ranges and templates

[Chris Wright via Digitalmars-d]

On Mon, 14 Dec 2015 20:52:15 +0000, Jack Stouffer wrote:
> C++ is doomed if you have to understand templates and iterators 
> to use the STL

C++ existed long before the STL. But a putative C++ clone that had sorely 
lacking documentation about iterators and put them everywhere in its 
standard library would struggle more than it would otherwise. It would be 
worse if what documentation existed were cluttered with dense syntax that 
novices agree is confusing. And doom would be assured if the standard 
library authors were dismissive of the needs of programmers who are not 
as familiar with the language as the core development team.

> Also, most of Phobos doesn't use ranges.

Quick survey by module:

std.algorithm: 6/6 modules.
std.array: yes.
std.ascii: no.
std.base64: yes.
std.bigint: no.
std.bitmanip: yes.
std.compiler: no.
std.complex: no.
std.concurrency: no.
std.container: 5/6 modules.
std.conv: yes.
std.csv: yes.
std.datetime: yes.
std.demangle: no.

At this point I got bored, but suffice it to say, a *lot* of Phobos uses 
ranges. And a lot more will. Ranges are central to modern D and to making 
composable functions.

Plus a lot of the stuff that does use ranges is pretty important and 
widely used and useful. It's the sort of thing that new programmers are 
pointed to and told "You should be using this."

Finally, requests for better documentation or to bear in mind people who 
have not been living and breathing D for months should not be 
controversial.