Clarify documentation around close, flush, and isopen

base/asyncevent.jl

@@ -9,7 +9,8 @@ Create a async condition that wakes up tasks waiting for it
 (by calling [`wait`](@ref) on the object)
 when notified from C by a call to `uv_async_send`.
 Waiting tasks are woken with an error when the object is closed (by [`close`](@ref)).
-Use [`isopen`](@ref) to check whether it is still active.
+Use [`isopen`](@ref) to check whether it is still active. A closed condition will
+not wake up tasks.
 
 This provides an implicit acquire & release memory ordering between the sending and waiting threads.
 """
@@ -74,7 +75,8 @@ Create a timer that wakes up tasks waiting for it (by calling [`wait`](@ref) on
 Waiting tasks are woken after an initial delay of at least `delay` seconds, and then repeating after
 at least `interval` seconds again elapse. If `interval` is equal to `0`, the timer is only triggered
 once. When the timer is closed (by [`close`](@ref)) waiting tasks are woken with an error. Use
-[`isopen`](@ref) to check whether a timer is still active. Use `t.timeout` and `t.interval` to read
+[`isopen`](@ref) to check whether a timer is still active. A closed timer will not fire.
+Use `t.timeout` and `t.interval` to read
 the setup conditions of a `Timer` `t`.
 
 ```julia-repl
@@ -206,6 +208,14 @@ end
 
 isopen(t::Union{Timer, AsyncCondition}) = @atomic :acquire t.isopen
 
+"""
+    close(t::Union{Timer, AsyncCondition})
+
+Close an object `t`. Once a timer or condition is closed, it will not produce
+a new event.
+
+See also: [`isopen`](@ref)
+"""
 function close(t::Union{Timer, AsyncCondition})
     t.handle == C_NULL && !t.isopen && return # short-circuit path, :monotonic
     iolock_begin()

base/io.jl

@@ -41,11 +41,9 @@ buffer_writes(x::IO, bufsize=SZ_UNBUFFERED_IO) = x
 """
     isopen(object)::Bool
 
-Determine whether an object - such as a stream or timer
--- is not yet closed. Once an object is closed, it will never produce a new event.
-However, since a closed stream may still have data to read in its buffer,
-use [`eof`](@ref) to check for the ability to read data.
-Use the `FileWatching` package to be notified when a stream might be writable or readable.
+Determine whether an object, such as an IO or timer, is not yet closed.
+
+See also: [`close`](@ref)
 
 # Examples
 ```jldoctest
@@ -63,11 +61,27 @@ false
 function isopen end
 
 """
-    close(stream)
+    close(io::IO)
+
+Close `io`. Performs a [`flush`](@ref) first.
+
+Closing an IO signals that its underlying resources (OS handle, network
+connections, etc) should be destroyed.
+A closed IO is in an undefined state and should not be written to or read from.
+When attempting to do so, the IO may throw an exception, continue to behave
+normally, or read/write zero bytes, depending on the implementation.
+However, implementations should make sure that reading to or writing from a
+closed IO does not cause undefined behaviour.
 
-Close an I/O stream. Performs a [`flush`](@ref) first.
+This function is generically defined to only `flush` the io. That allows
+wrapping IOs to close its underlying IO.
+
+See also: [`isopen`](@ref)
 """
-function close end
+function close(io::IO)
+    flush(io)
+    nothing
+end
 
 """
     closewrite(stream)
@@ -97,9 +111,11 @@ julia> read(io, String)
 function closewrite end
 
 """
-    flush(stream)
+    flush(io::IO)
 
-Commit all currently buffered writes to the given stream.
+Commit all currently buffered writes to the given io.
+This has a default implementation `flush(::IO) = nothing`, so may be called
+in generic IO code.
 """
 function flush end
 

base/iostream.jl

@@ -75,6 +75,16 @@ fd(s::IOStream) = RawFD(ccall(:jl_ios_fd, Clong, (Ptr{Cvoid},), s.ios))
 
 stat(s::IOStream) = stat(fd(s))
 
+"""
+    isopen(s::IOStream)
+
+Check if the stream is not yet closed.
+
+A closed `IOStream` may still have data to read in its buffer,
+use [`eof`](@ref) to check for the ability to read data.
+
+Use the `FileWatching` package to be notified when a file might be writable or readable.
+"""
 isopen(s::IOStream) = ccall(:ios_isopen, Cint, (Ptr{Cvoid},), s.ios) != 0
 
 function close(s::IOStream)