docs for Subscriber

I tried to make Subscriber nicer, but finally, I ended up with almost the same as what you proposed in https://github.com/ReactiveX/RxScala/pull/57.
So I decided to write some docs, so that library users and library developers hopefully will be less confused when looking at the code than I was ;-)