Simple step to making Ddoc better

[Adam D. Ruppe via Digitalmars-d]

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.