We need better documentation for functions with ranges and templates

Meta via Digitalmars-d digitalmars-d at puremagic.com
Mon Dec 14 12:44:03 PST 2015


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);


More information about the Digitalmars-d mailing list