Add nullability annotations to main API and extension points

[berrueta]

This PR adds nullability annotations (JSR 305) to the main API and extension points. For conciseness and safety, the annotations are not comprehensive. There is a lot of room to continue annotating, but in this PR I have selected the methods that are likely to have a bigger impact.

These annotations provide a richer API contract that allows compilers, IDEs and static analysis tools to do a better job at helping developers and preventing bugs.

For example, before this PR, if a developer wanted to implement a new Gen in Kotlin, the IDE would automatically generate the following skeleton:

class MyGenerator : Gen<String> {
    override fun generate(sourceOfRandomness: SourceOfRandomness?, generationStatus: GenerationStatus?): String {
        TODO("implementation goes here")
    }
}

The question marks after the parameter types indicate that the parameters are nullable, because the IDE does not know better and makes the safest choice on behalf of the developer (this is called a "platform type" in Kotlin). The developer then has two choices:

• keep the question marks and explicitly handle the nullable value, if the developer doesn't know better either and wants to be defensive, or
• remove the question marks to indicate to the compiler that the developer is sure the values are non-nullable. That requires the developer to understand the intention of the library creator.

With the changes in this PR, the two parameters are now annotated with @Nonnull in the interface. The IDE will generate the following skeleton:

class MyGenerator : Gen<String> {
    override fun generate(sourceOfRandomness: SourceOfRandomness, generationStatus: GenerationStatus): String {
        TODO("implementation goes here")
    }
}

Note the absence of question marks. The developer does not need to be defensive and handle a hypothetical null, and the type checker can guarantee that the implementation of the method is NPE-free.

The drawback of this change is that it may cause compilation errors in some applications. Going back to the first example, if the developer decided to keep the question marks, this PR will cause a compilation error, because the generate method in the application no longer overrides the generate method in the interface (they have different signatures). The fix is simple: just remove the question marks to match the signature of the interface. This problem may affect some Kotlin users, and potentially also Java applications using static analysis tools like Findbugs.

[pholser]

👀

[Jiehong]

Why do you add this dependency? It doesn't seem to be used anywhere.

[berrueta]

This dependency provides the javax.annotation.Nonnull and javax.annotation.Nullable annotations from JSR-305.

Alternatively we could use some other vendor-specific annotations with similar purpose, for example https://github.com/JetBrains/java-annotations