From 3780466a71530c86cee0f21c2cf37bd3c22e614f Mon Sep 17 00:00:00 2001
From: Markus Kuhn <Markus.Kuhn@cl.cam.ac.uk>
Date: Thu, 11 May 2023 18:25:17 +0100
Subject: [PATCH] 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 | 28 +++++++++++++++++++++++++---
 1 file changed, 25 insertions(+), 3 deletions(-)

diff --git a/base/io.jl b/base/io.jl
index 9c00c57576bac5..c71888ab48af68 100644
--- a/base/io.jl
+++ b/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