Update the documentation for the Channel interface

[dkhalanskyjb]

trafficstars

Note: a major piece of terminology that's changed in this is that when a channel is closed with a cause, it's no longer called a "failed channel". I found it immensely confusing to have channelResult.isClosed that means "the channel is closed", but channelResult.isFailed that doesn't mean "the channel is failed". Also, every cancelled channel is a "failed" channel by the definition of being closed with a cause, which doesn't seem to be the intention. So, I suggest that we remove mentions of "failed channels" throughout and replace them with "closed with a cause". Luckily, it's only relevant in a limited number of places.