On Friday, 18 December 2015 at 16:57:44 UTC, Sönke Ludwig wrote:
Agreed, do you have concrete ideas?
I think white space in the declaration would make a huge
difference, and your page does that already somewhat, putting the
params on separate lines.
Here's the ddoc definition for levenshteinDistance:
http://dlang.org/phobos/std_algorithm_comparison.html#.levenshteinDistance
---
size_t levenshteinDistance(alias equals = (a, b) => a == b,
Range1, Range2)(Range1 s, Range2 t) if (isForwardRange!Range1 &&
isForwardRange!Range2);
---
Here's the ddox definition:
https://dlang.org/library/std/algorithm/comparison/levenshtein_distance.html
---
size_t levenshteinDistance(alias equals, Range1, Range2)(
Range1 s,
Range2 t
)
if (isForwardRange!Range1 && isForwardRange!Range2);
---
I think the second one is nicer looking, but it also didn't show
the default argument and the template args could be broken more.
I think I'd write it:
---
size_t
levenshteinDistance
(
alias equals = (a, b) => a == b,
Range1,
Range2
)
(
Range1 s,
Range2 t
)
if (
isForwardRange!Range1 &&
isForwardRange!Range2
);
---
Or something like that. Plus syntax highlighting and linking of
recognized things. The parameters should link to details in the
Params: section, if present. `isForwardRange` should link back to
that definition. Heck, I wouldn't mind if `size_t` was a link too.
You know, I wouldn't even hate it if hovering over `Range1` in
the constraint or either param list highlighted it in the other
places it is mentioned too. A bit of script required but it can
help to visually tie it all in.
We can't rearrange the constraint to put them right next to each
other like `Range1, // isForwardRange!Range1` in the CT param
list since template constraints can be arbitrarily complex, but
some dynamic highlighting can achieve a similar effect.
One item per line might seem like overkill here, but I think it
pays off on complex types, specializations, or default values.
`(alias equals = (a, b) => a == b, Range1, Range2)` is kinda a
handful already and not even all that complex. Though, if the
names and types were highlighted it might mitigate this more than
plain text can allow.
I just really strongly feel that white space is our friend here
and we ought to be using it. Color and dynamic highlighting is
gravy on top of it.
One thing that could also be interesting (and easy to do) would
be to add parameter names in the "Functions" overview tables,
so that levenshteinDistance gets listed as
levenshteinDistance(equals, s, t). That could replace the
manually authored cheat sheet in many cases.
Yes, indeed.
