• via Digitalmars-d-bugs (36/38) Nov 02 2015 https://issues.dlang.org/show_bug.cgi?id=15275

via Digitalmars-d-bugs <digitalmars-d-bugs puremagic.com> writes:

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

          Issue ID: 15275
           Summary: Documentation for OutputRange lacking
           Product: D
           Version: D2
          Hardware: x86
                OS: Mac OS X
            Status: NEW
          Severity: enhancement
          Priority: P1
         Component: dlang.org
          Assignee: nobody puremagic.com
          Reporter: landergriffith+dlangbz gmail.com

As a newcomer to D, I wanted to write a library with an output stream that
std.stream.OutputStream would have been a good candidate for but in the docs
saw that the stream module is deprecated. I went in to IRC to ask what the
replacement is and was told to use ranges -- specifically an OutputRange.

On the documentation page for std.range
(http://dlang.org/phobos/std_range.html) I searched for OutputRange and the
*only* results are in the context of NullSink and tee. The tee part of the
documentation actually hyperlinks OutputRange, so clicking that I'd expect it
to take me somewhere that I can read more info about the OutputRange but it
goes nowhere (link in question:
http://dlang.org/phobos/std_range.html#OutputRange).

From the top of the page:

 Ranges generalize the concept of arrays, lists, or anything that involves
sequential access. This abstraction enables the same set of algorithms (see
std.algorithm) to be used with a vast variety of different concrete types. For
example, a linear search algorithm such as std.algorithm.find works not just
for arrays, but for linked-lists, input files, incoming network data, etc.

The last part of that mainly involves *input* data, not output data. Some of
the methods described involve mutating or combining the arrays but I'm somewhat
surprised the "put" method is not mentioned at least once on the page. Even
referring to the source was more helpful than the docs
(https://github.com/D-Programming-Language/phobos/blob/master/std/range/interfaces.d#L235
-- I was told in IRC that this isn't entirely accurate as I want the template
method but it helped some).

I think that the documentation page for std.range is seriously lacking info
about using an OutputRange and in general that streams are two-directional.
Perhaps a documentation improvement could also be made to the std.stream module
to describe the move to ranges instead as well.

--