Human unreadable documentation - the ugly seam between simple D and complex D

[Tobias Pankrath via Digitalmars-d]

> [skip]
> I'm not a native English speaker, but a range can start with a 
> needle? Where is the haystack? :)

Yes the output is awful, but that does not imply some kind of 
concepts is needed to make the documentation easier to 
understand. And Python's startsWith makes no use of a protocol. 
See here http://www.rafekettler.com/magicmethods.html for an 
explanation.

> Now that we're talking about creating your own sequences in 
> Python, it's time > to talk about protocols. Protocols are 
> somewhat similar to interfaces in other > languages in that 
> they give you a set of methods you must define. However, in > 
> Python protocols are totally informal and require no explicit 
> declarations to > implement. Rather, they're more like 
> guidelines.

It's similar to what we have, just with even less help from the 
language. (We can at least statically check that some arguments 
is e.g. a range).

> Anyway, in the Python built-in lib I didn't find any 
> levenshtheinDistance
Please calculate the levenshtein distance of "aaabc" and "ababc" 
both in python and D.

Then come back and tell me it was too hard in D compared to 
Python.

> , boyermooreFinder or 
> schschchcscshshscscshshscscssscsshcswarzSort.

Both are well known and useful algorithms. You might not know 
them but that's actually no argument not to include them in 
phobos. Their presence does not make the documentation any harder 
to understand or harder to find a startsWith function.

I don't buy this "There is a function I don't know, it's so hard 
to understand thing". That's like saying: I only need XML, don't 
put JSON in the stdlib because I will get confused! How should I 
anticipate that I don't need std.json when I just want to parse 
XML? I cannot even google that for me.