We need better documentation for functions with ranges and templates

[ZombineDev via Digitalmars-d]

On Tuesday, 15 December 2015 at 11:26:04 UTC, rumbu wrote:
>
> Looking at the .net source code, the Count extension method is 
> also doing a best effort "count" by querying the ICollection 
> interface.

Yes, I have looked at the source code, before writing this, so I 
knew exactly how it worked. In short : terrible, because it 
relies only on OOP. But that's not the point. Why should anyone 
need to look at the source code, to see what this function does? 
I thought this is what the docs were supposed to tell.

>
> public static int Count<TSource>(this IEnumerable<TSource> [...]
>
> The Remarks section clearly states the same thing:
>
> "If the type of source implements ICollection<T>, that 
> implementation is used to obtain the count of elements. 
> Otherwise, this method determines the count."
>
>
> And personally, I found the MS remark more compact and more 
> user friendly than:
> [...]

If you look at table at the beginning of page 
(https://dlang.org/phobos/std_range_primitives.html) you can 
clearly see a nice concise description of the function. Even if 
you don't know complexity theory there's the word "Compute" which 
should give you an idea that the function performs some 
non-trivial amount of work. Unlike:

> Returns the number of elements in a sequence.

Which implies that it only returns a number - almost like an 
ordinary getter property. I am scared to think that if back then 
C# got extension properties, it might have been implemented as 
such.

> Not everybody is licensed in computational complexity theory to 
> understand what O(n) means.

LOL. Personally, I would never want to use any software written 
by a programmer, who can't tell the difference.

Well ok, let's consider a novice programmer who hasn't studied 
yet complexity theory.

Option A: They look at the documentation and see there's some 
strange O(n) thing that they don't know. They look it up in 
google and find the wonderful world of complexity theory. They 
become more educated and are grateful the people who wrote the 
documentation for describing more accurately the requirements of 
the function. That way they can easily decide how using such 
function would impact the performance of their system.

Option B: They look at the documentation and see that there's 
some strange O(n) thing that they don't know. They decide that 
it's extremely inhumane for the docs to expect such significant 
knowledge from the reader and they decide to quit. Such novices 
that do not want to learn are better off choosing a different 
profession, than inflicting their poor written software on the 
world.