more detailed docstring for read!

The old `read!` docstring failed to describe how many bytes the
function reads and what its return value is.

base/io.jl

@@ -475,10 +475,32 @@ read(filename::AbstractString, args...) = open(io->read(io, args...), convert(St
 read(filename::AbstractString, ::Type{T}) where {T} = open(io->read(io, T), convert(String, filename)::String)
 
 """
-    read!(stream::IO, array::AbstractArray)
-    read!(filename::AbstractString, array::AbstractArray)
+    read!(stream::IO, a::AbstractArray)
+    read!(stream::IO, a::Ref)
+    read!(filename::AbstractString, a::Union{AbstractArray, Ref})
+
+Read `sizeof(a)` bytes of binary data from an I/O stream or file,
+store them in the memory allocated for `a`, then return `a`.
+
+Example:
+```jldoctest
+julia> read!(IOBuffer("Julia"), Vector{UInt8}(undef, 5))
+5-element Vector{UInt8}:
+ 0x4a
+ 0x75
+ 0x6c
+ 0x69
+ 0x61
+
+julia> read!(IOBuffer("Julia"), Matrix{UInt8}(undef, 2, 2))
+2×2 Matrix{UInt8}:
+ 0x4a  0x6c
+ 0x75  0x69
+
+julia> read!(IOBuffer("Julia"), Ref{Complex{UInt8}}(0))
+Base.RefValue{Complex{UInt8}}(0x4a + 0x75im)
+```
 
-Read binary data from an I/O stream or file, filling in `array`.
 """
 function read! end