Enhance java doc

I'm skeptical to this kind of spec-like-but-not-really-spec-style of Javadoc,
not only is it hard to keep in sync with the actual spec, but it is also potentially teaching the user the wrong things.
Can we keep the description simpler and less-spec-like and just refer to the spec for semantics?

Perhaps we should hoist the spec for Publisher, Subscriber etc into the JavaDoc on build?