Use Java annotations for API-related documentation

[magicDGS]

Similar to the Guava annotations or the barclay argparser ones we can add our own to make easier the live of developers using the library. My suggestion:

• Beta for non-stable API (might be changed in future releases). This would be part of the API eventually or maybe even remove, so users should use at their own risk.
• VisibleForTesting for public/protected methods that are only accessible for testing purposes.
• Hidden for classes that should be public/package-protected to be used in implementations, but they should not be used as an API (e.g., an abstract-class implementation to help constructing a ReadReader, but that might be change as required by the implementations. I use Hidden to keep it in line with barclay, but it could be name also Private or VisibleForHtsjdk (as a signature that it is only used for the API).
• Advance: for classes/methods that provides lower-level access or unsafe ones (e.g., getters/setters for SAMRecord int flag, which are not recommended). Another name might be Unsafe or something suggesting "do not use unless you know what you are doing".

Other options are:

• Experimental: if we want to use Beta for anything that it is still under development but it would be eventually released, and something that could be completely removed.

Maybe this is not that important at the current stage of development, but it might be for the release

[magicDGS]

Another option is to use the API guardian library (light, simple and containing most of the concepts that I would to have) or making something similar for us. Still, it does not resolve how to point out to advance methods (like bitwise flags in reads).