Doctests for some IO functions (#24922)

base/io.jl

@@ -110,27 +110,57 @@ function copy end
 function eof end
 
 """
-    read(stream::IO, T)
+    read(io::IO, T)
 
-Read a single value of type `T` from `stream`, in canonical binary representation.
+Read a single value of type `T` from `io`, in canonical binary representation.
 
-    read(stream::IO, String)
+    read(io::IO, String)
 
-Read the entirety of `stream`, as a String.
+Read the entirety of `io`, as a `String`.
+
+# Examples
+```jldoctest
+julia> io = IOBuffer("JuliaLang is a GitHub organization");
+
+julia> read(io, Char)
+'J': ASCII/Unicode U+004a (category Lu: Letter, uppercase)
+
+julia> io = IOBuffer("JuliaLang is a GitHub organization");
+
+julia> read(io, String)
+"JuliaLang is a GitHub organization"
+```
 """
 read(stream, t)
 
 """
-    write(stream::IO, x)
+    write(io::IO, x)
     write(filename::AbstractString, x)
 
 Write the canonical binary representation of a value to the given I/O stream or file.
 Return the number of bytes written into the stream.
 
 You can write multiple values with the same `write` call. i.e. the following are equivalent:
 
-    write(stream, x, y...)
-    write(stream, x) + write(stream, y...)
+    write(io, x, y...)
+    write(io, x) + write(io, y...)
+
+# Examples
+```jldoctest
+julia> io = IOBuffer();
+
+julia> write(io, "JuliaLang is a GitHub organization.", " It has many members.")
+56
+
+julia> String(take!(io))
+"JuliaLang is a GitHub organization. It has many members."
+
+julia> write(io, "Sometimes those members") + write(io, " write documentation.")
+44
+
+julia> String(take!(io))
+"Sometimes those members write documentation."
+```
 """
 function write end
 
@@ -199,9 +229,17 @@ wait_readbyte(io::AbstractPipe, byte::UInt8) = wait_readbyte(pipe_reader(io), by
 wait_close(io::AbstractPipe) = (wait_close(pipe_writer(io)); wait_close(pipe_reader(io)))
 
 """
-    nb_available(stream)
+    nb_available(io)
 
 Return the number of bytes available for reading before a read from this stream or buffer will block.
+
+# Examples
+```jldoctest
+julia> io = IOBuffer("JuliaLang is a GitHub organization");
+
+julia> nb_available(io)
+34
+```
 """
 nb_available(io::AbstractPipe) = nb_available(pipe_reader(io))
 
@@ -358,9 +396,22 @@ htol(x)
 
 
 """
-    isreadonly(stream) -> Bool
+    isreadonly(io) -> Bool
 
 Determine whether a stream is read-only.
+
+# Examples
+```jldoctest
+julia> io = IOBuffer("JuliaLang is a GitHub organization");
+
+julia> isreadonly(io)
+true
+
+julia> io = IOBuffer();
+
+julia> isreadonly(io)
+false
+```
 """
 isreadonly(s) = isreadable(s) && !iswritable(s)
 
@@ -789,6 +840,7 @@ Advance the stream `io` such that the next-read character will be the first rema
 which `predicate` returns `false`. If the keyword argument `linecomment` is specified, all
 characters from that character until the start of the next line are ignored.
 
+# Examples
 ```jldoctest
 julia> buf = IOBuffer("    text")
 IOBuffer(data=UInt8[...], readable=true, writable=false, seekable=true, append=false, size=8, maxsize=Inf, ptr=1, mark=-1)
@@ -819,6 +871,22 @@ end
 Read `io` until the end of the stream/file and count the number of lines. To specify a file
 pass the filename as the first argument. EOL markers other than `'\\n'` are supported by
 passing them as the second argument.
+
+# Examples
+```jldoctest
+julia> io = IOBuffer("JuliaLang is a GitHub organization.\n");
+
+julia> countlines(io)
+1
+
+julia> io = IOBuffer("JuliaLang is a GitHub organization.");
+
+julia> countlines(io)
+0
+
+julia> countlines(io, '.')
+1
+```
 """
 function countlines(io::IO, eol::Char='\n')
     isascii(eol) || throw(ArgumentError("only ASCII line terminators are supported"))

base/iobuffer.jl

@@ -38,6 +38,27 @@ Create an `IOBuffer`, which may optionally operate on a pre-existing array. If t
 readable/writable arguments are given, they restrict whether or not the buffer may be read
 from or written to respectively. The last argument optionally specifies a size beyond which
 the buffer may not be grown.
+
+# Examples
+```jldoctest
+julia> io = IOBuffer("JuliaLang is a GitHub organization.")
+IOBuffer(data=UInt8[...], readable=true, writable=false, seekable=true, append=false, size=35, maxsize=Inf, ptr=1, mark=-1)
+
+julia> read(io, String)
+"JuliaLang is a GitHub organization."
+
+julia> write(io, "This isn't writable.")
+ERROR: ArgumentError: ensureroom failed, IOBuffer is not writeable
+
+julia> io = IOBuffer(UInt8[], true, true, 34)
+IOBuffer(data=UInt8[...], readable=true, writable=true, seekable=true, append=false, size=0, maxsize=34, ptr=1, mark=-1)
+
+julia> write(io, "JuliaLang is a GitHub organization.")
+34
+
+julia> String(take!(io))
+"JuliaLang is a GitHub organization"
+```
 """
 IOBuffer(data::AbstractVector{UInt8}, readable::Bool=true, writable::Bool=false, maxsize::Integer=typemax(Int)) =
     GenericIOBuffer(data, readable, writable, true, false, maxsize)
@@ -51,14 +72,43 @@ end
 """
     IOBuffer() -> IOBuffer
 
-Create an in-memory I/O stream.
+Create an in-memory I/O stream, which is both readable and writable.
+
+# Examples
+```jldoctest
+julia> io = IOBuffer();
+
+julia> write(io, "JuliaLang is a GitHub organization.", " It has many members.")
+56
+
+julia> String(take!(io))
+"JuliaLang is a GitHub organization. It has many members."
+```
 """
 IOBuffer() = IOBuffer(true, true)
 
 """
     IOBuffer(size::Integer)
 
 Create a fixed size IOBuffer. The buffer will not grow dynamically.
+
+# Examples
+```jldoctest
+julia> io = IOBuffer(12)
+IOBuffer(data=UInt8[...], readable=true, writable=true, seekable=true, append=false, size=0, maxsize=12, ptr=1, mark=-1)
+
+julia> write(io, "Hello world.")
+12
+
+julia> String(take!(io))
+"Hello world."
+
+julia> write(io, "Hello world again.")
+12
+
+julia> String(take!(io))
+"Hello world "
+```
 """
 IOBuffer(maxsize::Integer) = (x=IOBuffer(StringVector(maxsize), true, true, maxsize); x.size=0; x)
 
@@ -262,6 +312,17 @@ isopen(io::GenericIOBuffer) = io.readable || io.writable || io.seekable || nb_av
 
 Obtain the contents of an `IOBuffer` as an array, without copying. Afterwards, the
 `IOBuffer` is reset to its initial state.
+
+# Examples
+```jldoctest
+julia> io = IOBuffer();
+
+julia> write(io, "JuliaLang is a GitHub organization.", "It has many members.")
+55
+
+julia> String(take!(io))
+"JuliaLang is a GitHub organization.It has many members."
+```
 """
 function take!(io::GenericIOBuffer)
     ismarked(io) && unmark(io)