On Tuesday, 15 December 2015 at 16:12:18 UTC, Chris Wright wrote:
> On Tue, 15 Dec 2015 09:09:43 +0000, Adrian Matoga wrote:
>
>> Fantastic example of why this strategy should be just banned.
>
> Just as well I wasn't recommending it as a long-term solution. I was more offering it as additional evidence that template definitions can get a bit large and people have known that this is a problem for documentation for eight years now.
>
> "Banned" is a strong term. Perhaps you simply meant it should not be recommended and should not be used in Phobos?

Yes, perhaps "strongly discouraged" would be a more appropriate wording.
version(StdDdoc) already appears about 40 times in Phobos, sometimes wrapping quite large blocks of declarations. I doubt the maintainability of such setup in the long term.

On Monday, 14 December 2015 at 19:04:46 UTC, bachmeier wrote:
> Something has to be done with the documentation for Phobos functions that involve ranges and templates.

Just today:

- "Where's the documentation for makeIndex?"

- http://imgur.com/4SQckvN

- "AHHHHHH!" *runs away*

On Wednesday, 16 December 2015 at 18:25:31 UTC, Luís Marques wrote:
> On Monday, 14 December 2015 at 19:04:46 UTC, bachmeier wrote:
>> Something has to be done with the documentation for Phobos functions that involve ranges and templates.
>
> Just today:
>
> - "Where's the documentation for makeIndex?"
>
> - http://imgur.com/4SQckvN
>
> - "AHHHHHH!" *runs away*

I've proposed a few changes to dlang.org and dmd that should help with this:

https://github.com/D-Programming-Language/dlang.org/pull/1169
https://github.com/D-Programming-Language/dmd/pull/5311

On Wednesday, 16 December 2015 at 18:25:31 UTC, Luís Marques wrote:
> On Monday, 14 December 2015 at 19:04:46 UTC, bachmeier wrote:
>> Something has to be done with the documentation for Phobos functions that involve ranges and templates.
>
> Just today:
>
> - "Where's the documentation for makeIndex?"
>
> - http://imgur.com/4SQckvN
>
> - "AHHHHHH!" *runs away*

It is all about how the details of function declaration is shown. If you look at the function's template parameters, function parameters, and conditionals separately, I do not think it is any complex at all.

On 12/15/2015 12:26 PM, rumbu wrote:
>
> And personally, I found the MS remark more compact and more user
> friendly than:
>
> "This is a best-effort implementation of length for any kind of range.
> If hasLength!Range, simply returns range.length without checking upTo
> (when specified). Otherwise, walks the range through its length and
> returns the number of elements seen. Performes Ο(n) evaluations of
> range.empty and range.popFront(), where n is the effective length of
> range."
>
> Not everybody is licensed in computational complexity theory to
> understand what O(n) means.

One doesn't need to know any results or definitions from complexity theory in order to understand what O(n) means. What it means here is that for large enough n the actual number is bounded from above by n multiplied by some unspecified constant.
(In contexts like this, there is generally also an informal assumption that the unspecified constants are reasonably small.)

On Thu, Dec 17, 2015 at 12:00:03AM +0100, Timon Gehr via Digitalmars-d wrote:
> On 12/15/2015 12:26 PM, rumbu wrote:
> >
> >And personally, I found the MS remark more compact and more user friendly than:
> >
> >"This is a best-effort implementation of length for any kind of range.  If hasLength!Range, simply returns range.length without checking upTo (when specified). Otherwise, walks the range through its length and returns the number of elements seen. Performes Ο(n) evaluations of range.empty and range.popFront(), where n is the effective length of range."
> >
> >Not everybody is licensed in computational complexity theory to
> >understand what O(n) means.
> 
> One doesn't need to know any results or definitions from complexity theory in order to understand what O(n) means. What it means here is that for large enough n the actual number is bounded from above by n multiplied by some unspecified constant.  (In contexts like this, there is generally also an informal assumption that the unspecified constants are reasonably small.)

Any programmer that has any pretense of caring about the performance of their code ought to know what O(n) means. It's not that hard to understand. There are plenty of online resources to learn about this, even if you didn't have the privilege of having received formal computer science education.


T

-- 
"Real programmers can write assembly code in any language. :-)" -- Larry Wall

On Wednesday, 16 December 2015 at 23:00:03 UTC, Timon Gehr wrote:
> On 12/15/2015 12:26 PM, rumbu wrote:
>>
>> And personally, I found the MS remark more compact and more user
>> friendly than:
>>
>> "This is a best-effort implementation of length for any kind of range.
>> If hasLength!Range, simply returns range.length without checking upTo
>> (when specified). Otherwise, walks the range through its length and
>> returns the number of elements seen. Performes Ο(n) evaluations of
>> range.empty and range.popFront(), where n is the effective length of
>> range."
>>
>> Not everybody is licensed in computational complexity theory to
>> understand what O(n) means.
>
> One doesn't need to know any results or definitions from complexity theory in order to understand what O(n) means. What it means here is that for large enough n the actual number is bounded from above by n multiplied by some unspecified constant.
> (In contexts like this, there is generally also an informal assumption that the unspecified constants are reasonably small.)

Perhaps it's the physicist in me, but I like this way of thinking about it:

Given a running time R(n), the time-complexity is given by O(f(n)) iff df/dn = lim_{n -> inf} dR(n)/dn

Is that also a correct expression? Obviously I'm papering over the discretisation, but well, I did say physicist... :)

On Thursday, 17 December 2015 at 00:06:05 UTC, John Colvin wrote:
>
> Given a running time R(n), the time-complexity is given by O(f(n)) iff df/dn = lim_{n -> inf} dR(n)/dn
>
> Is that also a correct expression? Obviously I'm papering over the discretisation, but well, I did say physicist... :)

That's how I think about it usually, but I think it's more general than just analyzing run-times of programs. You could use big O notation to classify any kind of function (wikipedia has a more mathematical definition).

On Monday, 14 December 2015 at 19:04:46 UTC, bachmeier wrote:
> Something has to be done with the documentation for Phobos functions that involve ranges and templates.
>
Many useful ideas in this thread. One I don't recall seeing - a standard way to denote whether a routine is lazy or eager. I'm finding this to be a key piece of information. Many standard library routines document this in the description, but presence and presentation is not very consistent. It'd be nice to have this presented in a standard way for routines operating on ranges.

--Jon

On Thursday, 17 December 2015 at 07:19:04 UTC, Jon D wrote:
> On Monday, 14 December 2015 at 19:04:46 UTC, bachmeier wrote:
>> Something has to be done with the documentation for Phobos functions that involve ranges and templates.
>>
> Many useful ideas in this thread. One I don't recall seeing - a standard way to denote whether a routine is lazy or eager. I'm finding this to be a key piece of information. Many standard library routines document this in the description, but presence and presentation is not very consistent. It'd be nice to have this presented in a standard way for routines operating on ranges.
>
> --Jon

Yes this something important that is missing. It is currently up to the documentation of a particular function to explain this. I think originally std.range was supposed to be lazy and std.algorithm - eager, but currently it's not a clear cut. Also in different contexts you may need a lazy version of an eager algorithm and vice-versa.