Improve JavaDoc

[dansiviter]

Could you improve the detail within the JavaDoc especially in relation to v2 to include expected life-cycle, scope and examples.

It appears the @ManagedService annotation functionality has changed significantly in relation to all your examples (including the tutorial) and now goes via ManagedAtmosphereHandler. It's difficult to understand the scope and life-cycle of this and how to obtain the AtmosphereResource from within @Message annotated methods if we want to broadcast manually. In #1170 you say use a @Get or @Post annotation, but the example you refer to doesn't which makes it very confusing.

Basically, if the JavaDoc was kept up-to-date it would make many of these issues disappear as we would be able to figure them out without digging into the code.

[jfarcand]

Duplicate of #810 . Thanks for filling the issue, I'm working on docs for 2.0 release. This is the blocker right now.