Improve, document, and link tools for automatically adding nullness annotations

[cpovirk]

We have a few in Error Prone's nullness directory, notably ReturnMissingNullable, which we have used to great effect. All those could be improved in various ways, and we have Google-internal issues filed about a few of those ways.

A bigger win would probably be to be able to run each one of them as a standalone Java binary, one that requires downloading no dependencies and one that can operate on an isolated source file without need of its dependencies. Doing this would restrict what we can do somewhat, but we can still easily add @Nullable to methods that return null, for example :)

The existing tools are not well documented. Part of the problem is that Error Prone's patching mode is complex, but we can sidestep that for the standalone tool I referred to above. Still, there will be more to document. A big part of that is documenting how to have the tools make all the changes that are 99.9999% likely to be correct (which you barely have to look at), then the changes that are merely very likely to be correct (which you can review more carefully), and perhaps so on down the line for changes that we're even less confident in but that still make a useful start for a human that is viewing them more as of a best guess that might save you some typing than as a near-indisputably correct judgment.

Then we'd want to direct users there from our documentation, such as from our forthcoming 1.0 blog post.

And we're not the only one with such tools:

• https://checkerframework.org/manual/#nullness-inference
• https://checkerframework.org/manual/#whole-program-inference
• I think https://github.com/uber/NullAway/blob/master/jar-infer/jar-infer-cli/README.md is somewhat different, but the NullAway folks may have pointers, and so may other people inside and outside the group.

[msridhar]

There is also https://github.com/ucr-riple/NullAwayAnnotator, which has been used to enroll millions of lines of code onto NullAway at Uber. /cc @lazaroclapp @yuxincs @nimakarimipour

[msridhar]

• I think https://github.com/uber/NullAway/blob/master/jar-infer/jar-infer-cli/README.md is somewhat different, but the NullAway folks may have pointers, and so may other people inside and outside the group.

This is more about inferring some annotations for bytecode; it's not suitable for adding annotations to source code.

[jkschneider]

We just wrote a blog post on how we mass-migrated all of the OpenRewrite JSR-305 meta-annotations to JSpecify across thousands of use sites with OpenRewrite recipes. This is open for others to use as well for similar situations: https://www.moderne.ai/blog/mass-migration-of-nullability-annotations-to-jspecify

[wmdietl]

We just wrote a blog post on how we mass-migrated all of the OpenRewrite JSR-305 meta-annotations to JSpecify across thousands of use sites with OpenRewrite recipes. This is open for others to use as well for similar situations: https://www.moderne.ai/blog/mass-migration-of-nullability-annotations-to-jspecify

@jkschneider Great blog post! OpenRewrite looks like a great tool for such a migration!
I was wondering about a few points:

1. NonNullApi is meta-annotated with @NullMarked and, similarly, NonNullFields is meta-annotated with NonNull. The use of NullMarked on the annotation type only means that within that scope non-null is the default. The use of NonNull on the annotation type has no meaning, see discussion in Applicability of TYPE_USE annotations to class declarations #7. The feature this seems to want is what has been discussed as Implies, which is not part of JSpecify 1.0.

2. The OpenRewrite annotations are both declaration and type use annotations and the article has a nice discussion about the meaning for inner/nested types. Where this is not so easy, and might warrant a note in your post, is with array types. When you have a field/parameter that is @Nullable Object[] x, in JSR 305 that meant that the reference itself is nullable and the array elements are non-nullable. In JSR 308/JSpecify, that is now Object @Nullable [] x. The original @Nullable Object[] x now means the reference is non-nullable, but the array elements are nullable. I'm sure you're aware of this difference, but thought it's worth calling out.
   (Having an annotation apply to both declarations and type uses is rather inconvenient, as for arrays types it produces an ambiguity.)