Document Base.BufferStream

[omus]

@vtjnash mentioned that Base.BufferStream should be exported. Before we do that we should document how this IO type is expected to be used.

Currently this IO type works differently from other more common IO types like IOBuffer and IOStream:

• mark/reset broken for BufferStream #24465
• Review of IO blocking behaviour  #24526

[omus]

IOBuffer() is a file-like object, so it is incompatible with streaming modification. Use BufferStream for a stream-like object.
– JuliaCloud/AWS.jl#433 (comment)

Based upon this comment we may want to have the abstract types FileIO <: IO and StreamIO <: IO to be able to dispatch against these two different approaches. Note: the existence of FileIO.jl probably means we will probably need to chose another name.

[vtjnash]

It seems that mark/reset methods just need to be implemented (pass-through to the underlying IOBuffer)

[c42f]

A couple of potential BufferStream issues I've noticed:

• It doesn't seem to block on write(). Is this intentional? It seems like it could lead to problems if used in pipeline-like situations where the writer is faster than the reader.
• skip() is not implemented for BufferStream (nor Pipe), but this can be useful even for streaming. For example in combination with Tar.jl as in https://discourse.julialang.org/t/how-to-plumb-together-download-uncompress-untar-without-writing-full-downloaded-file