Annotate Map, Map.Entry, and HashMap.

You can see the source files with the annotations in
https://android-review.googlesource.com/c/platform/libcore/+/699804
(which obviously is not intended for submission). The .jaif changes
here were copy-and-pasted from the results of running the
extract-annotations tool on those sources.

There's a tricky issue around some common methods,
e.g. get(Object). There are three types of Map implementation, all of
which exist in the wild and are permitted by spec:
(1) Ones that can hold nulls (e.g. HashMap).
(2) Ones that can't hold nulls, and get(null) returns null
etc. (e.g. Guava's ImmutableMap).
(3) Ones that can't hold nulls, and get(null) throws NPE
(e.g. ConcurrentHashMap).

There's no way that we can annotate Map.get's argument to reflect all
of these. If it was a K, we could annotate it as @NullFromTypeParam,
but as it's an Object, we can't. But even that wouldn't be able to
distinguish between cases (2) and (3). The logical choice here is to
annotate it as @Nullable and risk that users might get an NPE from
get(null) for certain implementations, which is better than making
get(null) an error even when it's legal.

For getOrDefault, the second argument is annotated as @Nullable,
because there's nothing saying you can't pass null; and consequently
we have to annotate the return type as @Nullable. The true behaviour
would be a bit like Checker Framework's @PolyNull, which says that the
return value can be null iff the argument is, except that here the
return value can be null if either the argument is or the type
parameter is @Nullable... Even CF can't express that.

For merge, the nullability of the return type matches that of the
third type parameter of the BiFunction argument. Again, even CF can't
express that, and again, we err on the side of @Nullable.

Test: make docs
Bug: 64930165
Change-Id: I2bb2dc9a4f216d66743fe5eac847174664290dcd

0 files changed, 0 insertions, 0 deletions