Re: We need better documentation for functions with ranges and templates

[Meta via Digitalmars-d]

On Monday, 14 December 2015 at 19:38:26 UTC, 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'm not sure what else to say here.

No, stuff like the following is indefensible. The current 
documentation is nearly opaque to newcomers and *needs* to be 
fixed.

bool isPermutation(AllocateGC allocate_gc, Range1, Range2)(Range1 
r1, Range2 r2) if (allocate_gc == AllocateGC.yes && 
isForwardRange!Range1 && isForwardRange!Range2 && 
!isInfinite!Range1 && !isInfinite!Range2);




Compare that with the DDOX output, which is at least a little bit 
more readable (but also leaves a lot of room for improvement).

bool isPermutation(std.typecons.Flag!("allocateGC").Flag 
allocate_gc, Range1, Range2)(
  Range1 r1,
  Range2 r2
)
if (allocate_gc == AllocateGC.yes && isForwardRange!Range1 && 
isForwardRange!Range2 && !isInfinite!Range1 && 
!isInfinite!Range2);