We need better documentation for functions with ranges and templates

[cym13 via Digitalmars-d]

On Tuesday, 15 December 2015 at 01:50:07 UTC, tcak wrote:
> On Tuesday, 15 December 2015 at 01:10:01 UTC, Chris Wright 
> wrote:
>> [...]
>
> Hiding conditionals does not seem like to be solution. Here is 
> my idea:
>
> Show the function:
> bool isSameLength(Range1, Range2)(Range1 r1, Range2 r2)
>
> Then show the conditions separately:
> if(
>   isInputRange!Range1 &&
>   isInputRange!Range2 &&
>   !isInfinite!Range1 &&
>   !isInfinite!Range2
> )
>
> I am not sure whether ddoc supports/can support this, but being 
> able to do this, and
> even adding separate comment on function and its conditionals 
> separately could be quite useful. I know just talking doesn't 
> make anything working, but idea is needed first.
>
> By the way, I wish "and", "or", "xor" were in the language as 
> in Pascal. Things could be more human friendly maybe.

I think a first step can be taken that doesn't even need changing 
DDOC's output: just add syntax highlighting to the line in order 
to emphasize "bool isSameLength(Range1, Range2)(Range1 r1, Range2 
r2)" and make it look distinct from the template constraint part. 
It won't solve every problems but to a beginners eye it reads 
like "this is what the important stuff is".