Complicated template constraints in function signatures of many Phobos functions severely affect readability of standard library documentation.
This could be mitigated by refactoring the constraints into separate template predicates invoked in the (now much shorter) template constraints. These predicated can then be descriptively documented as well.
E.g. instead of:
--------------------
ptrdiff_t countUntil(alias pred = "a == b", R, Rs...)(R haystack, Rs needles) if (isForwardRange!R && Rs.length > 0 && isForwardRange!(Rs[0]) == isInputRange!(Rs[0]) && is(typeof(startsWith!pred(haystack, needles[0]))) && (Rs.length
== 1 || is(typeof(countUntil!pred(haystack, needles[1..$])))));
--------------------
Use something like this:
--------------------
ptrdiff_t countUntil(alias pred = "a == b", R, Rs...)(R haystack,
Rs needles) if (canCountUntil!(pred, R, Rs));
/** A range can be counted if:
- R is a forward range
- pred is a valid string comparison predicate, or a function that can
compare R.front with Rs.front
- ...
*/
template canCountUntil(alias pred, R, Rs...)
{
...
}
--------------------
See also:
http://forum.dlang.org/post/[email protected]http://forum.dlang.org/post/[email protected]
What I think is importent is, that templates used as constraints are linked in the documenation.
Comment #3 by kiithsacmp — 2014-12-19T13:13:57Z
(In reply to hsteoh from comment #1)
> A more comprehensive solution would be:
> https://issues.dlang.org/show_bug.cgi?id=13676
I think these are orthogonal; both are needed to make the docs readable. Regardless of style tricks, a wall-of-text constraint in a function signature is going to stay a wall-of-text.
Comment #4 by robert.schadek — 2024-12-01T16:23:21Z