If I understand it correctly, the current policy in Phobos is
that range methods should use static nested structs to avoid the
name clutter and document the capabilities of the returned ranges
in the documentation.
However there are a lot of old functions that still use public
structs, which leads to the rather confusing documentation output
in std.range:
Chunks · chunks · Cycle · cycle ... evenChunks · EvenChunks ·
FrontTransversal · frontTransversal · ... · indexed · Indexed ·
... · lockstep · Lockstep · .. · Recurrence · recurrence ·
RefRange · refRange · repeat · Repeat · ... · sequence · Sequence
· SortedRange · ... · Take · take · ... Transversal · transversal
· TransverseOptions · zip · Zip
(off-topic: it's quite interesting to see that sometimes the
structs are before the method and sometimes after it)
Two arguments to keep exposing the structs are that (1) an API
user can explicitly specify the return type (in contrast to auto)
and (2) one can see the capabilities of the struct in the
documentation.
There are many cases where methods in these structs are optional
and depend on the capabilities of the input range (e.g. backward,
length, random access, ...). I could imagine that
1) We rework ddoc, s.t. it doesn't list these structs in the
overview and adds the struct methods to the function (could get
ugly)
2) We deprecate those exposed structs and make them
private/nested (does anyone know whether it's common to depend on
those structs?)
What are your thoughts on this matter?
(This is a follow-up from a short discussion with Jakob Ovrum on
github [1].)
[1] https://github.com/D-Programming-Language/phobos/pull/4027
