Remove @Deprecated from @Preview and @BetaApi methods and classes

[bitwiseman]

The @Deprecated annotation on @Preview and @BetaApi methods and class results quite a bit of confusion. People assume these methods are actually deprecated and going away, when they are not. Further, there are a growing number of actually deprecated methods in this library this will eventually go away. We should find a better way to inform users that methods are in preview or beta.

@marcoferrer
From your work on #1001 and #1002, perhaps you'd have input here.

Can we use ArchUnit to check that methods with those annotations have some specific text in their JavaDoc titles, for example "(BETA)" or "(PREVIEW)"? Or perhaps we could write a checkstyle rule?

[marcoferrer]

You hit the nail on the head. I was experimenting with a couple of options locally. We can take a route similar to what guava does with their @Beta annotation. The options are either publish an annotation processor that checks for usages and prints out warnings during compilation or publish errorprone / findbugs plugins. The latter would require work to support each individual checker framework whereas the former would work generically across all jvm build systems.

Another option is we could provide an arch rule in either documentation examples or published artifacts. Then users would be able to either implement the test based on the example.

If we publish a set of rules for users to consume, whether it is via annotation processor, checker plugin, or arch test, it would at least allow us to update recommended checks as new features are implemented and the sdk is iterated on.

Thoughts?

[marcoferrer]

Side note, moving in this direction would also allow us to expose configuration options to users so that they may restrict preview usage in their codebase to only a subset of preview APIs.

[bitwiseman]

@marcoferrer
I was going for something simpler, enforcing some indicator in JavaDoc. I don't want to spend a lot of cycles on this or force consumers of this library to spend cycles, if possible. The main point is to let consumers know what methods are stableand which may change. If we must do something, I'd say an annotation processor sounds best to me. I'd use the @Beta annotation, but we don't want to take a guava dependency if possible.

[bitwiseman]

Edited - Instead of moving this information into JavaDoc, we should move it into code. See #1017 and #1179. This is just to remove the @Deprecated annotations from everywhere they aren't needed.