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

[rumbu via Digitalmars-d]

On Friday, 27 March 2015 at 13:07:30 UTC, Panke wrote:
> On Thursday, 26 March 2015 at 21:36:56 UTC, rumbu wrote:
>> On Thursday, 26 March 2015 at 19:45:19 UTC, Alex Parrill wrote:
>>> On Thursday, 26 March 2015 at 19:32:53 UTC, Idan Arye wrote:
>>>> ...snip...
>>>
>>> So tl;dr; make the template constraints in ddoc less 
>>> prominent?
>>>
>>> The "new library reference preview" under Resources seems to 
>>> already have this (example: 
>>> http://dlang.org/library/std/algorithm/searching/starts_with.html)
>>
>> This will not solve the readability problem:
>>
>> - what is a range?
>> - what is a needle?
>> - what is a predicate?
>>
>> Phobos is reinventing the OOP encapsulation without providing 
>> the minimal tools. IMHO, something similar to "interface" is 
>> mandatory to define constraints for "range" and the 
>> relationship between "needle" and "range".
>
> Never heard that complain about python's protocols which have no
> language support whatsoever.

I've never used Python, so take this as a live experiment:

I googled for "startswith python":

str.startswith(prefix[, start[, end]])
Return True if string starts with the prefix, otherwise return 
False. prefix can also be a tuple of prefixes to look for. With 
optional start, test string beginning at that position. With 
optional end, stop comparing string at that position.

In 3 seconds, I understood the basic usage, without ANY knowledge 
about Python. Even if I don't know Python, the brackets told me 
that "start" and "end" are optional. str, prefix, start, end - 
comprehensible simple words. The only thing remaining is the 
"tuple" thing. But I can use this function without knowing what a 
"tuple" is.

Looked also in the source code to find out that startsWith is 
locale sensitive, something ignored in phobos.

https://hg.python.org/cpython/file/4ebe1ede981e/Objects/stringobject.c#l2903

Now compare with this:

uint startsWith(alias pred = "a == b", Range, Needles...)(Range 
doesThisStart, Needles withOneOfThese) if (isInputRange!Range && 
Needles.length > 1 && is(typeof(.startsWith!pred(doesThisStart, 
withOneOfThese[0])) : bool) && 
is(typeof(.startsWith!pred(doesThisStart, withOneOfThese[1..$])) 
: uint));
bool startsWith(alias pred = "a == b", R1, R2)(R1 doesThisStart, 
R2 withThis) if (isInputRange!R1 && isInputRange!R2 && 
is(typeof(binaryFun!pred(doesThisStart.front, withThis.front)) : 
bool));
bool startsWith(alias pred = "a == b", R, E)(R doesThisStart, E 
withThis) if (isInputRange!R && 
is(typeof(binaryFun!pred(doesThisStart.front, withThis)) : bool));
*Checks whether the given input range starts with (one of) the 
given needle(s).*

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

Anyway, in the Python built-in lib I didn't find any 
levenshtheinDistance, boyermooreFinder or 
schschchcscshshscscshshscscssscsshcswarzSort.