Add annotations for null/non-null and checking return value

[sharwell]

Usability in modern Java IDEs would be improved if the code were annotated with the following or equivalent:

• @Nonnull
• @Nullable
• @CheckReturnValue (especially helpful for transformation methods on immutable collections)

Given that @CheckReturnValue is not present in org.jetbrains:annotations, which alternative is the least likely to cause problems for consumers of the library? Would com.google.code.findbugs:jsr305 be appropriate for most (or all) users?

💡 Currently this library has no runtime dependencies aside from the JRE itself.

Here are some use cases of interest:

1. Ability to use the library from an Eclipse plug-in (OSGi)
2. Ability to use the library from a non-OSGi plug-in
3. Ability of modern IDEs to automatically recognize the annotations and report problems when client code fails to follow a declared restriction