Fix issue 16970 - Fix deprecations and warnings when compiling Phobos

[edi33416]

Fixed ddocs in order to remove warnings when compiling html phobos, as mentioned on bugzilla.

I did not touch std/experimental/ndslice, since it's going to be deprecated.

[dlang-bot]

Fix	Bugzilla	Description
✓	16970	Fix deprecations and warnings when compiling Phobos

[edi33416]

Removed Example from ddoc and just made the unittest part of the docs, because:

• it was doing the same thing
• in case of a change in the API, we do not need to worry about modifying the example as well (that is why we have ///unittest)

[wilzbach]

Yes in general ddoced examples are horrible, because we can't ensure that they even compile.
As I seem not to be able to add a comment in the lines outside of the diff: maybe you could replace the commented writefln with assert's, so that it won't look to weird to a reader?
Note that for the rendered documentation we are considering to replace assert's like a == b automatically with a writeln equivalent

[wilzbach]

@@@BUG@@@ immediately caught my attention ;-)

[wilzbach]

what is the motivation for removing LREF? It creates nice, clickable __L__ocal reference, e.g.:

http://dlang.org/phobos/std_range.html#.take

[edi33416]

No reason, just a mistake due to rushing. Will undo

[wilzbach]

You could try

static if (is(typeof(R.init[0 .. $]) == R))
    return input[0 .. min(n, $)];
else
   return input[0 .. min(n, input.length)];

(and obviously add a couple of tests for it)

[edi33416]

Could you explain what is the difference between the two return statements?
I thought that $ and length are equivalent.

Are you considering the fact that a range might define opDollar, but not length? If so, the hasSlicing template constraint would be false.

I am starting to think that this bug comment is a residue

[andralex]

Some ranges define length but not opDollar. IMHO we shouldn't cater to them.

[wilzbach]

I thought that $ and length are equivalent.

Unfortunately they are not - opDollar needs to be defined separately :/
The rationale is that thus one can have special overloads that can be faster.
However, this makes using $ very, very error-prone - even in Phobos:

https://issues.dlang.org/show_bug.cgi?id=16073

IMHO we shouldn't cater to them.

Yes also it would be nice if opDollar would automatically alias to length if not defined and there is length defined.

I am starting to think that this bug comment is a residue

Well kind of. It's still true that opDollar simply might not be defined if hasSlicing is true, but there's no point of having this comment there
-> leave as it is currently and just remove the bug comment ;-)

[wilzbach]

Yes in general ddoced examples are horrible, because we can't ensure that they even compile.
As I seem not to be able to add a comment in the lines outside of the diff: maybe you could replace the commented writefln with assert's, so that it won't look to weird to a reader?
Note that for the rendered documentation we are considering to replace assert's like a == b automatically with a writeln equivalent

[andralex]

@wilzbach thx please approve as well when happy

[andralex]

Some ranges define length but not opDollar. IMHO we shouldn't cater to them.

[wilzbach]

thx please approve as well when happy

@edi33416 please remove the bug comment and squash - we should be good to go ;-)

[wilzbach]

We now verify with CircleCi that public examples are runnable (also part of the style Makefile target)

out/std_socket.d(13): Deprecation: std.socket.softUnittest is not visible from module std_socket
out/std_socket.d(13): Error: function std.socket.softUnittest is not accessible from module std_socket

[edi33416]

I missed that softUnittest has a private scope. Fixed it

[wilzbach]

Thanks a lot @edi33416