Recommended (new) APIs and more example code

[roeschter]

This is a test edit to verify style guides.

Starting to make good on my promise to improve the documentation.

Purpose:

1. Point users to the recommended (new) way of using Jetstream
2. Add more example code snipplets
3. Make sure such guidelines and code snipplet appear as early as possible in the developers journey. In this case on the Connection class.
4. More detailed examples would then be in ConsumerContext and StreamContext

[scottf]

LGTM

[roeschter]

Will fix Javadoc errors

[roeschter]

Fixed various Javadoc errors and warning. Added links to overview.html
Javadoc processes without wanrings
Done editing - will continue on another branch.

[scottf]

@roeschter There is a test failing, but I fixed and merged it a few days ago. Can you update your branch

[roeschter]

Cleaned up