We need better documentation for functions with ranges and templates

[H. S. Teoh via Digitalmars-d]

On Mon, Dec 14, 2015 at 08:08:20PM +0000, Jack Stouffer via Digitalmars-d wrote:
> On Monday, 14 December 2015 at 19:56:29 UTC, dnewbie wrote:
[...]
> >On the otherhand, imagine a newbie looking:
> >
> >bool isSameLength(Range1, Range2)(Range1 r1, Range2 r2) if
> >(isInputRange!Range1 && isInputRange!Range2 && !isInfinite!Range1 &&
> >!isInfinite!Range2);
> 
> They can look at the examples below and see that the function accepts
> strings and arrays. And they can look at the parameters section and
> see that r1 and r2 need to be "finite input range"s if they can't read
> the function signature.

While I agree with you in principle, I also think that one has to admit,
that function signature looks far more scary than it actually is. A lot
of this can probably be attributed to lack of control over the
formatting of various elements in the signature. It's just a single
dense blob of stuff that you have to stare at for at least 2 full
seconds before you can parse it completely (or longer if you're new to
D).

Imagine, for example, if the docs were to be formatted a little better,
say something like this:

	bool isSameLength(Range1, Range2)
	                 (Range1 r1, Range2 r2)
		if (isInputRange!Range1 &&
		    isInputRange!Range2 &&
		    !isInfinite!Range1 &&
		    !isInfinite!Range2)

The sig constraint block can be rendered in a different font / font
size / color / whatever. The CT parameters similarly can be visually
distinguished from the RT parameters.

Currently, this isn't possible yet, due to limitations in ddoc:

	https://issues.dlang.org/show_bug.cgi?id=13676

In theory, though, this should not be hard to add -- somebody just has
to take the time to implement it in ddoc.d. Once we have that, it's just
a matter of putting in the right macros in the ddoc stylesheets.


T

-- 
Computerese Irregular Verb Conjugation: I have preferences.  You have biases.  He/She has prejudices. -- Gene Wirchenko