document isopen(::Channel)

[mrufsvold]

This PR has two purposes --

1. Add some documentation for public API
2. Add a small note about a footgun I've hit a few times: !isopen(ch) does not mean that you are "done" with the channel because buffered channels can still have items left in them that need to be taken.

[vtjnash]

I believe the unbuffered channel example here is misleading, since even unbuffered channels can have concurrent blocked put! operations that mean there is isready data after !isopen

[vtjnash]

Suggested change

	Unbuffered channel:
	```jldoctest
	julia> c = Channel{Int}()
	julia> isopen(c)
	true
	julia> close(c)
	julia> isopen(c)
	false

[mrufsvold]

Really? I thought, once an unbuffered channel is closed, all concurrent put!s error?

julia> ch = Channel()
Channel{Any}(0) (empty)

julia> t = @async put!(ch, 1)
Task (runnable) @0x000002028d9f1f10

julia> isready(ch)
true

julia> close(ch)

julia> isopen(ch)
false

julia> isready(ch)
false

julia> fetch(t)
ERROR: TaskFailedException
Stacktrace:
 [1] wait
   @ .\task.jl:359 [inlined]
 [2] fetch(t::Task)
   @ Base .\task.jl:379
 [3] top-level scope
   @ REPL[20]:1

    nested task error: InvalidStateException: Channel is closed.
    Stacktrace:
     [1] try_yieldto(undo::typeof(Base.ensure_rescheduled))
       @ Base .\task.jl:945
     [2] wait()
       @ Base .\task.jl:1009
     [3] wait(c::Base.GenericCondition{ReentrantLock}; first::Bool)
       @ Base .\condition.jl:130
     [4] wait
       @ .\condition.jl:125 [inlined]
     [5] put_unbuffered(c::Channel{Any}, v::Int64)
       @ Base .\channels.jl:387
     [6] put!(c::Channel{Any}, v::Int64)
       @ Base .\channels.jl:342
     [7] (::var"#17#18")()
       @ Main .\REPL[15]:1

[vtjnash]

Ah, okay, I didn't know that. I guess that makes sense though

[mrufsvold]

This is why I keeping hitting this issue. Since the behavior of unbuffered and buffered channels is subtly different, I'll add a buffer to a channel and introduce silent bugs elsewhere! Thank you for the review!

[vtjnash]

Can you fix the couple of doctest failures and then this can merge

[vtjnash]

Suggested change

	julia> c = Channel{Int}()
	julia> c = Channel{Int}();

[mrufsvold]

@vtjnash I don't understand the outstanding doc error. It says that the final isready(c) evaluates to true when the docstring expects false. However, when I run the code in the REPL, it matches the docstring.

Edit: I'm wondering if the comment shifted things down and confused the docstring test? It also said that take!(c) returned true, so it seems to be an issue with aligning expected and actual outputs, not with the logic of the code.

Edit 2: even after moving the comments around, it's still failing.