[Issue 18341] New: Documentation for std.array.split is confusing/incorrect

[d-bugmail at puremagic.com]

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

          Issue ID: 18341
           Summary: Documentation for std.array.split is
                    confusing/incorrect
           Product: D
           Version: D2
          Hardware: x86_64
                OS: Other
            Status: NEW
          Severity: trivial
          Priority: P1
         Component: dlang.org
          Assignee: nobody at puremagic.com
          Reporter: bachmeil at yahoo.com

The documentation says "Eagerly split the string s into an array of words,
using whitespace as delimiter." Then under See Also it says
"std.algorithm.iteration.splitter for a version that splits using any
separator." Then one of the examples shows how to use split with a
user-specified separator:

writeln(split("hello world")); // ["hello", "world"]
writeln(split("192.168.0.1", ".")); // ["192", "168", "0", "1"]

auto a = split([1, 2, 3, 4, 5, 1, 2, 3, 4, 5], [2, 3]);
writeln(a); // [[1], [4, 5, 1], [4, 5]]

Something has to be wrong.

1. I think the last example is intended to be used with the other version of
split. 
2. I don't understand why the user is referred to splitter when split can be
used with any separator. AFAICT, the difference between split and splitter is
that split is eager and splitter is lazy, and it has nothing to do with
specifying the separator.
3. The statement "split allocates memory, so the same effect can be achieved
lazily using std.algorithm.iteration.splitter." should not be located inside an
example.

--