WIP: Add some documentation to WebSocket and Error.

[najamelan]

So as I have been figuring out from the source code how tungstenite works, I felt it would be silly to just let that disappear when my memory fades, so I wrote documentation, hoping it will also save others time.

This isn't polished:

• read_message, write_pending and close should probably have an Errors section which lists all the possible outcomes
• some of it can hopefully be simplified after other issues are resolved, like: User issued pong messages should probably be kept separate from replies to pings. #78.
• some of the error handling hasn't actually been resolved, like: Do not allow sending messages after sending a close frame #74 and the docs will need updating when it does
• design improvements might make things more convenient, like: Review the implementation of WebSocketContext::read_message #76 which might also change behavior as described here.
• write_pending is a user facing method that does not use check_active. I haven't really dug into what that really implies. It probably returns Ok(()) forever for clients, instead of returning ConnectionClosed. It should probably be looked into and docs updated.
• I removed the part of doc from Error::AlreadyClosed that claimed this would be returned when writing after receiving a Close message, since it was simply not true, but this error kind should probably be re-evaluated after discussion in Review closing the connection #77.

I have no intention of polishing this, cause I have my own chores to do on my own libraries, but "Allow edits from maintainers" is on. Please use it.

[daniel-abramov]

👍

[najamelan]

@application-developer-DA Thanks for working through all of my feedback. I know it's long and I know I'm a nitpick, but I hope tungstenite is really a better library for it.
;)